{ "openapi": "3.1.0", "info": { "title": "Ledgr API", "version": "v4", "description": "The Ledgr API is the same API the Ledgr apps use — there is no reduced\n\"integration\" surface, and no endpoint the product uses that you cannot.\n\n## Authenticating\n\n1. The customer creates an API key in **Settings → Roles → API keys**, choosing\n its scopes, and gives it to you. They can revoke it at any time, and a\n revoked key stops working on the next request rather than when its last\n token expires.\n2. `POST /auth/token` with `Authorization: Bearer ` returns an access token\n valid for one hour.\n3. Send that token as `Authorization: Bearer ` on every other call.\n\nYou never need a customer's password. If an integration asks for one, that is\na reason to refuse it.\n\n## What a key can do\n\nThree limits apply together, and the narrowest wins:\n\n- **The tenant's plan.** An endpoint in an unlicensed module returns\n `403 MODULE_NOT_LICENSED` regardless of scopes.\n- **The key's scopes.** `403 INSUFFICIENT_SCOPE`, naming the scope needed.\n- **The role of the user who created the key.** A key made by a Viewer cannot\n write, whatever scopes it was given.\n\n## Rate limits\n\n120 requests per minute per key by default. Every response carries\n`X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`, so you can\npace yourself without probing for the ceiling. Over the limit returns `429` with\n`Retry-After`.\n\n## Multi-company tenants\n\nA tenant may hold several companies. Send `X-Company-Id: ` to act within\none; `GET /api/companies` lists them. Company-scoped endpoints reject a request\nwith no company when the tenant has more than one, rather than picking for you.\n\n## Money and dates\n\nAmounts are decimal numbers in the document's currency, ZAR unless stated.\nDates are `YYYY-MM-DD`. Timestamps are ISO-8601 with an offset, in UTC.", "contact": { "name": "Ledgr developer support", "url": "https://www.ledgrsa.com/developers/" } }, "servers": [ { "url": "https://www.ledgrsa.com", "description": "Production" } ], "tags": [ { "name": "Authentication" }, { "name": "Two-factor authentication" }, { "name": "Tenant, plan & entitlements" }, { "name": "Users, roles & security" }, { "name": "API keys" }, { "name": "Webhooks" }, { "name": "Files & attachments" }, { "name": "Search, insights & deadlines" }, { "name": "Push notifications" }, { "name": "Contacts" }, { "name": "Invoicing & quotes" }, { "name": "Payments & gateways" }, { "name": "Customer portal" }, { "name": "Sales CRM" }, { "name": "Customer ordering portal API" }, { "name": "Expenses & claims" }, { "name": "Purchasing & suppliers" }, { "name": "Banking & reconciliation" }, { "name": "General ledger" }, { "name": "Reports & analytics" }, { "name": "SARS returns" }, { "name": "Payroll" }, { "name": "Leave" }, { "name": "Inventory" }, { "name": "Job cards" }, { "name": "Service contracts" }, { "name": "Time tracking" }, { "name": "Workflows" }, { "name": "Rental & hire" }, { "name": "Bills of materials" }, { "name": "Material planning (MRP)" }, { "name": "Production & work orders" }, { "name": "Procurement" }, { "name": "Supplier portal API" }, { "name": "Supplier workspace, buyer side" }, { "name": "Logistics & fleet" }, { "name": "Driver app API" }, { "name": "Multi-company & consolidation" }, { "name": "Accountant workspace" }, { "name": "WhatsApp" }, { "name": "External ingest (API key)" }, { "name": "Inbound webhooks" }, { "name": "Operations & discovery" }, { "name": "Point of sale" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "A Ledgr API key (ledgr_…), used ONLY at POST /auth/token to obtain an access token. Keys are created in Roles & Users → API Keys and can be revoked there at any time." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "An access token from POST /auth/token (integrations) or POST /auth/login (first-party clients). Send as: Authorization: Bearer ." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "DeleteApiBillsByIdResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "ledgerNotice": { "type": "string" } } }, "DeleteApiCrmLeadsByIdResponse": { "description": "Shared by 55 operations.", "type": "object", "properties": { "status": { "type": "string" } } }, "DeleteApiMrpCheckPlansByIdResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } } } }, "DeleteApiWorkflowsCommentsByIdResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "itemId": { "type": "string" }, "authorUserId": { "type": "string" }, "authorName": { "type": "string" }, "body": { "type": "string" }, "createdAt": { "type": "string" } } }, "GetApiBankFeedsResponseFeedsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "bankAccountId": { "type": "string" }, "bankAccountName": { "type": "string" }, "investecAccountId": { "type": "string" }, "investecAccountName": { "type": "string" }, "investecAccountMasked": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "lastSyncAt": { "type": "string" }, "lastSyncStatus": { "type": "string" }, "lastError": { "type": "string" }, "syncCount": { "type": "integer" }, "totalImported": { "type": "integer" }, "consecutiveFailures": { "type": "integer" }, "nextAttemptAt": { "type": "string" }, "syncFrom": { "type": "string", "format": "date" }, "createdAt": { "type": "string" }, "needsAttention": { "type": "boolean" }, "attentionReason": { "type": "string" } } }, "GetApiBillsByIdPaymentsResponseItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "billId": { "type": "string" }, "contactId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "method": { "type": "string" }, "reference": { "type": "string" }, "bankAccountId": { "type": "string" }, "remaining": { "type": "number" } } }, "GetApiBillsCreditNotesResponseItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "creditNoteNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "creditedBillId": { "type": "string" }, "creditedBillNumber": { "type": "string" }, "supplierName": { "type": "string" }, "net": { "type": "number" }, "vat": { "type": "number" }, "total": { "type": "number" }, "settlement": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": "string" }, "supplierReturnId": { "type": "string" }, "refundedAt": { "type": "string" } } }, "GetApiBillsPaymentRunResponseBlockedItem": { "type": "object", "properties": { "billId": { "type": "string" }, "vendor": { "type": "string" }, "contactId": { "type": "string" }, "billNumber": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "payee": { "type": "string" }, "blockedReason": { "type": "string" }, "warning": { "type": "string" } } }, "GetApiBillsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "companyId": { "type": "string" }, "costCentreId": { "type": "string" }, "vendor": { "type": "string" }, "billNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRate": { "type": "number" }, "currency": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "recurring": { "type": "boolean" }, "frequency": { "type": "string" }, "nextDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "recurrenceActive": { "type": "boolean" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "paidAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "ledgerNotice": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBillsRequestLinesItem" } }, "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "sellerDeclarationUrl": { "type": "null" }, "sellerDeclarationSignedOn": { "type": "null" } } }, "GetApiBomByBomIdAttachmentsResponse": { "description": "Shared by 10 operations.", "type": "object", "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkflowsItemsByIdResponseAttachmentsItem" } } } }, "GetApiBomLinesByLineIdAlternatesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "alternates": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBomLinesByLineIdAlternatesResponseAlternatesItem" } } } }, "GetApiBomLinesByLineIdAlternatesResponseAlternatesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "alternateProductId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "qtyPer": { "type": "number" }, "priority": { "type": "integer" }, "notes": { "type": "string" }, "available": { "type": "number" } } }, "GetApiBomOverviewResponseMissingBomsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "qty": { "type": "number" }, "sourceType": { "type": "string" }, "onHand": { "type": "number" }, "shortfall": { "type": "number" }, "unitCost": { "type": "number" }, "extendedCost": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "supplierName": { "type": "string" } } }, "GetApiBomPlanningBufferSuggestionResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "productName": { "type": "string" }, "sku": { "type": "string" }, "qtyPrecision": { "type": "integer" }, "abcClass": { "type": "string" }, "leadTimeDays": { "type": "integer" }, "currentSafetyStock": { "type": "number" }, "currentReorderPoint": { "type": "null" }, "historyMonths": { "type": "integer" }, "blocker": { "type": "null" }, "serviceLevel": { "type": "integer" }, "monthlyMean": { "type": "number" }, "monthlySwing": { "type": "number" }, "leadTimeDemand": { "type": "number" }, "safetyStock": { "type": "number" }, "reorderPoint": { "type": "number" } } }, "GetApiBomProductsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "isTracked": { "type": "boolean" } } }, "GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseNonControllingInterest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "shareOfProfit": { "type": "number" }, "shareOfNetAssets": { "type": "number" }, "perEntity": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseNonControllingInterestPerEntityItem" } }, "whollyOwnedGroup": { "type": "boolean" } } }, "GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseNonControllingInterestPerEntityItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "effectiveOwnershipPercent": { "type": "number" }, "nonControllingPercent": { "type": "number" }, "standaloneProfit": { "type": "number" }, "standaloneNetAssets": { "type": "number" }, "nonControllingProfit": { "type": "number" }, "nonControllingNetAssets": { "type": "number" } } }, "GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseScope": { "description": "Shared by 4 operations.", "type": "object", "properties": { "rootCompanyId": { "type": "string" }, "rootName": { "type": "string" }, "companyIds": { "type": "array", "items": { "type": "string" } }, "companyCount": { "type": "integer" }, "excluded": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseScopeExcludedItem" } }, "maxDepth": { "type": "integer" } } }, "GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseScopeExcludedItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "reason": { "type": "string" } } }, "GetApiCompanyHierarchyByIdConsolidatedEliminationsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseScope" }, "eliminated": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedEliminationsResponseExternalItem" } }, "external": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedEliminationsResponseExternalItem" } }, "eliminatedTurnover": { "type": "number" }, "eliminatedBalances": { "type": "number" }, "externalTurnover": { "type": "number" } } }, "GetApiCompanyHierarchyByIdConsolidatedEliminationsResponseExternalItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "fromCompanyId": { "type": "string" }, "fromName": { "type": "string" }, "toCompanyId": { "type": "string" }, "toName": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "open": { "type": "boolean" } } }, "GetApiCompanyHierarchyPickerResponseItemsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tradeName": { "type": "string" }, "depth": { "type": "integer" }, "breadcrumb": { "type": "string" }, "isActive": { "type": "boolean" }, "baseCurrency": { "type": "string" }, "childCount": { "type": "integer" } } }, "GetApiContactsAgedDebtorsResponseTotals": { "type": "object", "properties": { "contactId": { "type": "string" }, "contactName": { "type": "string" }, "current": { "type": "number" }, "days30": { "type": "number" }, "days60": { "type": "number" }, "days90": { "type": "number" }, "total": { "type": "number" }, "overdue": { "type": "number" }, "days1to30": { "type": "number" }, "notYetDue": { "type": "number" } } }, "GetApiContactsByContactIdTransactionsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "occurredAt": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "vatRate": { "type": "number" }, "externalRef": { "type": "string" }, "metadata": { "type": "string" }, "status": { "type": "string" }, "invoiceId": { "type": "string" }, "invoicedAt": { "type": "string" }, "createdAt": { "type": "string" } } }, "GetApiContactsByIdBalanceResponseAgeing": { "description": "Shared by 2 operations.", "type": "object", "properties": { "current": { "type": "number" }, "days30": { "type": "number" }, "days60": { "type": "number" }, "days90": { "type": "number" }, "overdue": { "type": "number" }, "days1to30": { "type": "number" }, "notYetDue": { "type": "number" } } }, "GetApiContactsByIdConsentResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "contactId": { "type": "string" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiContactsByIdConsentResponseChannelsItem" } }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiContactsByIdConsentResponseHistoryItem" } }, "notMarketing": { "type": "string" } } }, "GetApiContactsByIdConsentResponseChannelsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "channel": { "type": "string" }, "label": { "type": "string" }, "mayMarket": { "type": "boolean" }, "latest": { "$ref": "#/components/schemas/GetApiContactsByIdConsentResponseHistoryItem" } } }, "GetApiContactsByIdConsentResponseHistoryItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "channel": { "type": "string" }, "channelLabel": { "type": "string" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "method": { "type": "string" }, "methodLabel": { "type": "string" }, "note": { "type": "string" }, "recordedBy": { "type": "string" }, "recordedAt": { "type": "string" } } }, "GetApiContactsByIdCustomerPortalResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "contactId": { "type": "string" }, "customerName": { "type": "string" }, "enabled": { "type": "boolean" }, "token": { "type": "string" }, "url": { "type": "string" }, "expiresAt": { "type": "string" }, "lastSeenAt": { "type": "string" }, "offeredProductCount": { "type": "integer" } } }, "GetApiContactsByIdInvoicesResponseInvoicesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "documentType": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "total": { "type": "number" }, "amountDue": { "type": "number" }, "status": { "type": "string" } } }, "GetApiContactsByIdPriceListResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "contactId": { "type": "string" }, "priceList": { "$ref": "#/components/schemas/GetApiContactsByIdPriceListResponsePriceList" } } }, "GetApiContactsByIdPriceListResponsePriceList": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "companyId": { "type": "string" }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiContactsByIdPriceListResponsePriceListPricesItem" } } } }, "GetApiContactsByIdPriceListResponsePriceListPricesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "type": "string" }, "unitPrice": { "type": "number" } } }, "GetApiContactsByIdResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactType": { "type": "string" }, "name": { "type": "string" }, "tradingName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "mobile": { "type": "string" }, "vatNumber": { "type": "string" }, "registrationNo": { "type": "string" }, "creditLimit": { "type": "number" }, "creditUsed": { "type": "number" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" }, "postalAddressLine1": { "type": "string" }, "postalAddressLine2": { "type": "string" }, "postalCity": { "type": "string" }, "postalProvince": { "type": "string" }, "postalPostalCode": { "type": "string" }, "postalCountry": { "type": "string" }, "currency": { "type": "string" }, "paymentTerms": { "type": "integer" }, "notes": { "type": "string" }, "isActive": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "GetApiContactsByIdSupplierPortalResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "contactId": { "type": "string" }, "supplierName": { "type": "string" }, "enabled": { "type": "boolean" }, "token": { "type": "string" }, "url": { "type": "string" }, "expiresAt": { "type": "string" }, "lastSeenAt": { "type": "string" } } }, "GetApiContactsInformationOfficerResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "companyId": { "type": "string" }, "recorded": { "type": "boolean" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "regulatorRegistration": { "type": "string" }, "statement": { "type": "string" } } }, "GetApiContactsPromisesResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "promisedDate": { "type": "string", "format": "date" }, "note": { "type": "string" }, "status": { "type": "string" } } }, "GetApiCrmBccAddressResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "address": { "type": "string" } } }, "GetApiCrmLeadFormResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "url": { "type": "string" } } }, "GetApiDocumentsInboxAddressResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "configured": { "type": "boolean" }, "address": { "type": "string" }, "note": { "type": "string" } } }, "GetApiDocumentsInboxByIdResponseItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "documentKind": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "pageCount": { "type": "integer" }, "supplierName": { "type": "string" }, "documentDate": { "type": "string", "format": "date" }, "totalAmount": { "type": "number" }, "currency": { "type": "string" }, "confidence": { "type": "integer" }, "exactText": { "type": "boolean" }, "fromEmail": { "type": "string" }, "subject": { "type": "string" }, "receivedAt": { "type": "string" }, "expenseId": { "type": "string" }, "billId": { "type": "string" }, "duplicateOfId": { "type": "string" }, "duplicateNote": { "type": "string" }, "error": { "type": "string" }, "fileUrl": { "type": "string" }, "splitFromId": { "type": "string" }, "splitIndex": { "type": "integer" }, "splitCount": { "type": "integer" }, "splitNote": { "type": "string" }, "statementAccountRef": { "type": "string" }, "statementStart": { "type": "string", "format": "date" }, "statementEnd": { "type": "string", "format": "date" }, "statementTransactionCount": { "type": "integer" }, "statementImported": { "type": "integer" }, "statementDuplicates": { "type": "integer" }, "statementBalances": { "type": "boolean" }, "bankAccountId": { "type": "string" }, "bankAccountName": { "type": "string" }, "statementNote": { "type": "string" } } }, "GetApiDocumentsInboxResponseCounts": { "description": "Shared by 3 operations.", "type": "object", "properties": { "key": { "type": "integer" } } }, "GetApiDocumentsOcrResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "ok": { "type": "boolean" }, "engine": { "type": "string" }, "documentKind": { "type": "string" }, "extraction": { "$ref": "#/components/schemas/GetApiDocumentsOcrResponseExtraction" }, "rawText": { "type": "string" }, "ocrResultId": { "type": "string" }, "failure": { "type": "string" }, "error": { "type": "string" }, "manualEntryRequired": { "type": "boolean" }, "variant": { "type": "string" }, "passes": { "type": "integer" }, "pageCount": { "type": "integer" }, "pagesRead": { "type": "integer" }, "truncated": { "type": "boolean" }, "exactText": { "type": "boolean" }, "duplicateOf": { "$ref": "#/components/schemas/GetApiDocumentsOcrResponseDuplicateOf" }, "suggestion": { "$ref": "#/components/schemas/GetApiDocumentsOcrResponseSuggestion" } } }, "GetApiDocumentsOcrResponseDuplicateOf": { "description": "Shared by 2 operations.", "type": "object", "properties": { "ocrResultId": { "type": "string" }, "scannedAt": { "type": "string" }, "expenseId": { "type": "string" }, "billId": { "type": "string" }, "message": { "type": "string" } } }, "GetApiDocumentsOcrResponseExtraction": { "description": "Shared by 3 operations.", "type": "object", "properties": { "supplierName": { "type": "string" }, "supplierVatNumber": { "type": "string" }, "documentNumber": { "type": "string" }, "documentDate": { "type": "string", "format": "date" }, "subtotal": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRatePercent": { "type": "number" }, "total": { "type": "number" }, "currency": { "type": "string" }, "categoryHint": { "type": "string" }, "litres": { "type": "number" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiDocumentsOcrResponseExtractionLineItemsItem" } }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiDocumentsOcrResponseExtractionFieldsItem" } }, "reconciliation": { "$ref": "#/components/schemas/GetApiDocumentsOcrResponseExtractionReconciliation" }, "overallConfidence": { "type": "integer" }, "engineConfidence": { "type": "integer" }, "engineScored": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object" } }, "droppedLowConfidence": { "type": "array", "items": { "type": "string" } }, "manualEntryRequired": { "type": "boolean" } } }, "GetApiDocumentsOcrResponseExtractionFieldsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "name": { "type": "string" }, "confidence": { "type": "integer" }, "source": { "type": "string" }, "evidence": { "type": "string" } } }, "GetApiDocumentsOcrResponseExtractionLineItemsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "amount": { "type": "number" }, "confidence": { "type": "integer" } } }, "GetApiDocumentsOcrResponseExtractionReconciliation": { "description": "Shared by 3 operations.", "type": "object", "properties": { "subtotalPlusVatMatchesTotal": { "type": "boolean" }, "impliedVatRatePercent": { "type": "number" }, "vatRateRecognised": { "type": "boolean" }, "discrepancy": { "type": "number" }, "lineItemsSum": { "type": "number" }, "lineItemsMatchSubtotal": { "type": "boolean" } } }, "GetApiDocumentsOcrResponseSuggestion": { "description": "Shared by 3 operations.", "type": "object", "properties": { "category": { "type": "string" }, "contactId": { "type": "string" }, "reason": { "type": "string" } } }, "GetApiEmployeesByIdEquityResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "employeeId": { "type": "string" }, "race": { "type": "string" }, "gender": { "type": "string" }, "disabled": { "type": "boolean" }, "foreignNational": { "type": "boolean" }, "occupationalLevel": { "type": "string" }, "updatedAt": { "type": "string" } } }, "GetApiExpensesApprovalLimitsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "limits": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiExpensesApprovalLimitsResponseLimitsItem" } }, "mayChange": { "type": "boolean" } } }, "GetApiExpensesApprovalLimitsResponseLimitsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "roleId": { "type": "string" }, "roleName": { "type": "string" }, "maxAmount": { "type": "number" } } }, "GetApiExpensesApprovalPolicyResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "secondApprovalFrom": { "type": "number" }, "approvers": { "type": "integer" }, "mayChange": { "type": "boolean" }, "summary": { "type": "string" } } }, "GetApiExpensesByIdResponse": { "description": "Shared by 7 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "accountId": { "type": "string" }, "companyId": { "type": "string" }, "costCentreId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "vendor": { "type": "string" }, "supplierVatNumber": { "type": "string" }, "category": { "type": "string" }, "amount": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRate": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "receiptUrl": { "type": "string" }, "notes": { "type": "string" }, "rejectionReason": { "type": "string" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "approvedBy": { "type": "string" }, "approvedByName": { "type": "string" }, "approvedAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "ledgerNotice": { "type": "string" }, "timeProjectId": { "type": "string" }, "timeProjectName": { "type": "string" }, "rechargeable": { "type": "boolean" }, "rechargeInvoiceId": { "type": "string" } } }, "GetApiExpensesCategoryBudgetsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "category": { "type": "string" }, "monthlyBudget": { "type": "number" } } }, "GetApiExpensesClaimRunResponseBlockedItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "claimant": { "type": "string" }, "employeeId": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" }, "status": { "type": "string" }, "stage": { "type": "string" }, "receiptUrl": { "type": "string" }, "blockedReason": { "type": "string" }, "runId": { "type": "string" } } }, "GetApiExpensesCountResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "total": { "type": "integer" } } }, "GetApiFixedAssetsCapitalisationPolicyResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "threshold": { "type": "number" }, "smallItemLimit": { "type": "number" } } }, "GetApiFixedAssetsDeferredTaxResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "yearEnd": { "type": "string", "format": "date" }, "carryingAmount": { "type": "number" }, "taxValue": { "type": "number" }, "temporaryDifference": { "type": "number" }, "ratePercent": { "type": "number" }, "requiredBalance": { "type": "number" }, "bookedBalance": { "type": "number" }, "movement": { "type": "number" }, "unmappedAssets": { "type": "array", "items": { "type": "string" } }, "declinedReason": { "type": "string" } } }, "GetApiFranchiseUnitsByIdReportResponseCompaniesItemStatementRevenueItem": { "type": "object", "properties": { "name": { "type": "string" }, "amount": { "type": "number" }, "accountId": { "type": "string" } } }, "GetApiFranchiseUnitsResponseUnitsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "linkId": { "type": "string" }, "franchiseeName": { "type": "string" }, "status": { "type": "string" }, "invitedAt": { "type": "string" }, "acceptedAt": { "type": "string" } } }, "GetApiFxRatesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "baseCurrency": { "type": "string" }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiFxRatesResponseRatesItem" } }, "anyStale": { "type": "boolean" }, "summary": { "type": "string" } } }, "GetApiFxRatesResponseRatesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "fromCurrency": { "type": "string" }, "toCurrency": { "type": "string" }, "rate": { "type": "number" }, "asOf": { "type": "string" }, "source": { "type": "string" }, "fetchedAt": { "type": "string" }, "stale": { "type": "boolean" } } }, "GetApiGiftVouchersByIdResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "faceValue": { "type": "number" }, "balance": { "type": "number" }, "status": { "type": "string" }, "issuedOn": { "type": "string", "format": "date" }, "expiresOn": { "type": "string", "format": "date" }, "contactId": { "type": "string" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiGiftVouchersByIdResponseMovementsItem" } } } }, "GetApiGiftVouchersByIdResponseMovementsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "kind": { "type": "string" }, "amount": { "type": "number" }, "on": { "type": "string", "format": "date" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" } } }, "GetApiIntercompanyTransactionsByIdResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "fromCompanyId": { "type": "string" }, "toCompanyId": { "type": "string" }, "transactionDate": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "exchangeRate": { "type": "number" }, "accountIdFrom": { "type": "string", "format": "date" }, "accountIdTo": { "type": "string", "format": "date" }, "status": { "type": "string" }, "settledOn": { "type": "string", "format": "date" }, "settledAt": { "type": "string" }, "settledByName": { "type": "string" }, "settlementReference": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "GetApiInventoryAdjustmentReasonsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventoryAdjustmentReasonsResponseReasonsItem" } }, "requireReason": { "type": "boolean" } } }, "GetApiInventoryAdjustmentReasonsResponseReasonsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "builtIn": { "type": "boolean" } } }, "GetApiInventoryBackordersResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "orderId": { "type": "string" }, "number": { "type": "string" }, "contactName": { "type": "string" }, "backordered": { "type": "number" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventoryBackordersResponseItemLinesItem" } } } }, "GetApiInventoryBackordersResponseItemLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "lineId": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "ordered": { "type": "number" }, "backordered": { "type": "number" } } }, "GetApiInventoryBatchesByIdRecallResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "direction": { "type": "string" }, "rootBatchId": { "type": "string" }, "rootBatchNumber": { "type": "string" }, "rootProductName": { "type": "string" }, "rootSku": { "type": "string" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpBatchTraceResponseNodesItem" } }, "maxDepth": { "type": "integer" }, "truncated": { "type": "boolean" }, "unaccountedQty": { "type": "number" }, "receivers": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventoryBatchesByIdRecallResponseReceiversItem" } }, "receivedQty": { "type": "number" }, "onHandQty": { "type": "number" }, "quarantined": { "type": "boolean" } } }, "GetApiInventoryBatchesByIdRecallResponseReceiversItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "batchId": { "type": "string" }, "batchNumber": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "qty": { "type": "number" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "documentNumber": { "type": "string" }, "date": { "type": "string", "format": "date" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } }, "GetApiInventoryBinsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "locationId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "products": { "type": "integer" } } }, "GetApiInventoryBuildsByIdResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "bomId": { "type": "string" }, "bomName": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "locationId": { "type": "string" }, "qtyBuilt": { "type": "number" }, "status": { "type": "string" }, "componentCost": { "type": "number" }, "labourCost": { "type": "number" }, "overheadCost": { "type": "number" }, "totalCost": { "type": "number" }, "unitCost": { "type": "number" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "builtAt": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventoryBuildsByIdResponseLinesItem" } } } }, "GetApiInventoryBuildsByIdResponseLinesItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "componentProductId": { "type": "string" }, "componentName": { "type": "string" }, "qtyRequired": { "type": "number" }, "qtyConsumed": { "type": "number" }, "unitCost": { "type": "number" }, "totalCost": { "type": "number" }, "short": { "type": "boolean" } } }, "GetApiInventoryCycleCountsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "cadence": { "type": "string" }, "scope": { "type": "string" }, "abcClass": { "type": "string" }, "binId": { "type": "string" }, "binCode": { "type": "string" }, "active": { "type": "boolean" }, "lastPeriod": { "type": "string" } } }, "GetApiInventorySerialsByIdResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "serial": { "$ref": "#/components/schemas/GetApiInventorySerialsResponseItem" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySerialsByIdResponseEventsItem" } } } }, "GetApiInventorySerialsByIdResponseEventsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "fromStatus": { "type": "string" }, "toStatus": { "type": "string" }, "occurredAt": { "type": "string" }, "reference": { "type": "string" }, "notes": { "type": "string" } } }, "GetApiInventorySerialsResponseItem": { "description": "Shared by 7 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "variantId": { "type": "string" }, "serialNumber": { "type": "string" }, "batchId": { "type": "string" }, "locationId": { "type": "string" }, "supplier": { "type": "string" }, "receivedDate": { "type": "string", "format": "date" }, "unitCost": { "type": "number" }, "status": { "type": "string" }, "soldDate": { "type": "string", "format": "date" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "autoAssigned": { "type": "boolean" }, "warrantyExpiry": { "type": "string", "format": "date" }, "warrantyDaysRemaining": { "type": "integer" }, "underWarranty": { "type": "boolean" }, "notes": { "type": "string" }, "createdAt": { "type": "string" } } }, "GetApiInventorySuppliersResponseItem": { "description": "Shared by 10 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "GetApiInvoicesByIdAttachmentsResponseItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "attachmentId": { "type": "string" }, "filename": { "type": "string" }, "caption": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "sequence": { "type": "integer" }, "uploadedByName": { "type": "string" }, "createdAt": { "type": "string" }, "sendWithDocument": { "type": "boolean" } } }, "GetApiInvoicesByIdInstalmentCreditResponse": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "customerName": { "type": "string" }, "status": { "type": "string" }, "deliveredOn": { "type": "string", "format": "date" }, "cashPrice": { "type": "number" }, "vatInCashPrice": { "type": "number" }, "deposit": { "type": "number" }, "principalDebt": { "type": "number" }, "termMonths": { "type": "integer" }, "annualRatePercent": { "type": "number" }, "referenceRatePercent": { "type": "number" }, "creditTypeLabel": { "type": "string" }, "maximumRatePercent": { "type": "number" }, "initiationFee": { "type": "number" }, "monthlyServiceFee": { "type": "number" }, "instalment": { "type": "number" }, "costOfCredit": { "type": "number" }, "totalPayable": { "type": "number" }, "principalOutstanding": { "type": "number" }, "chargesOutstanding": { "type": "number" }, "balance": { "type": "number" }, "paidToDate": { "type": "number" }, "nextDueOn": { "type": "string", "format": "date" }, "nextInstalment": { "type": "number" }, "schedule": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdInstalmentCreditResponseScheduleItem" } }, "statement": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdInstalmentCreditResponseStatementItem" } } } }, "GetApiInvoicesByIdInstalmentCreditResponseScheduleItem": { "description": "Shared by 7 operations.", "type": "object", "properties": { "number": { "type": "integer" }, "dueOn": { "type": "string", "format": "date" }, "instalment": { "type": "number" }, "interest": { "type": "number" }, "fees": { "type": "number" }, "capital": { "type": "number" }, "balanceAfter": { "type": "number" }, "charged": { "type": "boolean" }, "chargeNumber": { "type": "string" } } }, "GetApiInvoicesByIdInstalmentCreditResponseStatementItem": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "on": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "balanceAfter": { "type": "number" }, "documentNumber": { "type": "string" } } }, "GetApiInvoicesByIdLaybyResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "laybyId": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string" }, "total": { "type": "number" }, "held": { "type": "number" }, "stillOwed": { "type": "number" }, "feePercent": { "type": "number" }, "feeIfCancelledNow": { "type": "number" }, "refundIfCancelledNow": { "type": "number" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdLaybyResponseMovementsItem" } }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" } } }, "GetApiInvoicesByIdLaybyResponseMovementsItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "amount": { "type": "number" }, "on": { "type": "string", "format": "date" }, "method": { "type": "string" }, "reference": { "type": "string" }, "invoiceNumber": { "type": "string" } } }, "GetApiInvoicesByIdResponse": { "description": "Shared by 8 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "documentType": { "type": "string" }, "invoiceNumber": { "type": "string" }, "status": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "exchangeRate": { "type": "number" }, "subtotal": { "type": "number" }, "discountTotal": { "type": "number" }, "vatTotal": { "type": "number" }, "total": { "type": "number" }, "amountPaid": { "type": "number" }, "amountDue": { "type": "number" }, "vatRegistered": { "type": "boolean" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "terms": { "type": "string" }, "sourceDocumentId": { "type": "string" }, "decidedAt": { "type": "string" }, "decidedByName": { "type": "string" }, "declineReason": { "type": "string" }, "costCentreId": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponseLinesItem" } }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponsePaymentsItem" } }, "reminders": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponseRemindersItem" } }, "contactRemindersPaused": { "type": "boolean" }, "tcs": { "type": "string" }, "bankDetails": { "type": "string" }, "footer": { "type": "string" }, "deposit": { "$ref": "#/components/schemas/PostApiInvoicesRequestDeposit" }, "picking": { "$ref": "#/components/schemas/PostApiInvoicesRequestPicking" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "GetApiInvoicesByIdResponseLinesItem": { "description": "Shared by 11 operations.", "type": "object", "properties": { "id": { "type": "string" }, "lineNumber": { "type": "integer" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "discountRate": { "type": "number" }, "vatRate": { "type": "number" }, "vatInclusive": { "type": "boolean" }, "lineSubtotal": { "type": "number" }, "discountAmount": { "type": "number" }, "vatAmount": { "type": "number" }, "lineTotal": { "type": "number" }, "accountId": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "discountType": { "type": "string" }, "discountFixed": { "type": "number" }, "kind": { "type": "string" }, "productCode": { "type": "string" }, "warehouseBin": { "type": "string" } } }, "GetApiInvoicesByIdResponsePaymentsItem": { "description": "Shared by 10 operations.", "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "method": { "type": "string" }, "reference": { "type": "string" }, "createdAt": { "type": "string" } } }, "GetApiInvoicesByIdResponseRemindersItem": { "description": "Shared by 8 operations.", "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "sentDate": { "type": "string", "format": "date" }, "channel": { "type": "string" }, "createdAt": { "type": "string" } } }, "GetApiJobCardsReportsWipResponseRowsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "jobCardId": { "type": "string" }, "jobNumber": { "type": "string" }, "title": { "type": "string" }, "contactName": { "type": "string" }, "status": { "type": "string" }, "ageDays": { "type": "integer" }, "cost": { "type": "number" }, "billable": { "type": "number" } } }, "GetApiJobCardsTechniciansResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "defaultChargeRate": { "type": "number" }, "defaultCostRate": { "type": "number" }, "defaultStockLocationId": { "type": "string" }, "defaultStockLocationName": { "type": "string" } } }, "GetApiLandedCostsDefaultsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "supplierContactId": { "type": "string" }, "supplierName": { "type": "string" }, "productId": { "type": "string" }, "productSku": { "type": "string" }, "chargeType": { "type": "string" }, "label": { "type": "string" }, "percentOfValue": { "type": "number" }, "capitalise": { "type": "boolean" }, "active": { "type": "boolean" }, "notes": { "type": "string" }, "specificity": { "type": "integer" } } }, "GetApiLedgerAnalysisDimensionsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "slot": { "type": "integer" }, "name": { "type": "string" }, "enabled": { "type": "boolean" } } }, "GetApiLedgerBooksOpenResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "date": { "type": "string", "format": "date" } } }, "GetApiLedgerBudgetByAccountResponseRevenueItem": { "type": "object", "properties": { "accountId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "accountType": { "type": "string" }, "budget": { "type": "number" }, "actual": { "type": "number" }, "variance": { "type": "number" }, "variancePct": { "type": "number" } } }, "GetApiLedgerJournalBatchesByIdResponseJournalsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "journalId": { "type": "string" }, "journalNumber": { "type": "string" }, "journalDate": { "type": "string", "format": "date" }, "total": { "type": "number" } } }, "GetApiLedgerJournalsByIdAttachmentsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "attachmentId": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" } } }, "GetApiLogisticsBoardResponseItemLastPosition": { "description": "Shared by 6 operations.", "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "accuracyM": { "type": "number" }, "speedKph": { "type": "number" }, "headingDeg": { "type": "number" }, "recordedAt": { "type": "string" }, "receivedAt": { "type": "string" }, "batteryPercent": { "type": "integer" }, "source": { "type": "string" }, "tripId": { "type": "string" }, "vehicleId": { "type": "string" }, "driverId": { "type": "string" }, "ageMinutes": { "type": "integer" } } }, "GetApiLogisticsCostsResponseRunsItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "tripDate": { "type": "string", "format": "date" }, "status": { "type": "string" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "driverId": { "type": "string" }, "driverName": { "type": "string" }, "distanceKm": { "type": "number" }, "drops": { "type": "integer" }, "driverHours": { "type": "number" }, "fuel": { "type": "number" }, "other": { "type": "number" }, "labour": { "type": "number" }, "standing": { "type": "number" }, "total": { "type": "number" }, "perKm": { "type": "number" }, "perDrop": { "type": "number" }, "revenue": { "type": "number" }, "margin": { "type": "number" }, "marginPercent": { "type": "number" }, "gaps": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsCostsResponseRunsItemLinesItem" } }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsCostsResponseRunsItemStopsItem" } } } }, "GetApiLogisticsCostsResponseRunsItemLinesItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" } } }, "GetApiLogisticsCostsResponseRunsItemStopsItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "stopId": { "type": "string" }, "sequence": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "charge": { "type": "number" } } }, "GetApiLogisticsInspectionChecklistResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsInspectionChecklistResponseItemsItem" } }, "standard": { "type": "array", "items": { "type": "string" } } } }, "GetApiLogisticsInspectionChecklistResponseItemsItem": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } } }, "GetApiLogisticsServicingResponseItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "vehicleId": { "type": "string" }, "registration": { "type": "string" }, "everyKm": { "type": "integer" }, "everyMonths": { "type": "integer" }, "standingCostPerKm": { "type": "number" }, "odometerKm": { "type": "number" }, "lastServiceOn": { "type": "string", "format": "date" }, "lastServiceKm": { "type": "number" }, "state": { "type": "string" }, "stateLabel": { "type": "string" }, "dueAtKm": { "type": "number" }, "dueOn": { "type": "string", "format": "date" }, "kmLeft": { "type": "number" }, "daysLeft": { "type": "integer" }, "estimatedOn": { "type": "string", "format": "date" }, "sentence": { "type": "string" } } }, "GetApiLogisticsSettingsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "officePhone": { "type": "string" }, "companyPhone": { "type": "string" } } }, "GetApiLogisticsStopsByIdCustomerResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "stopId": { "type": "string" }, "trackPath": { "type": "string" }, "podPath": { "type": "string" }, "linkValidDays": { "type": "integer" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPhone": { "type": "string" }, "updatesOptedOut": { "type": "boolean" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdCustomerResponseNoticesItem" } }, "rating": { "type": "integer" }, "ratingComment": { "type": "string" }, "ratedAt": { "type": "string" } } }, "GetApiLogisticsStopsByIdCustomerResponseNoticesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "event": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" }, "recipient": { "type": "string" }, "detail": { "type": "string" }, "at": { "type": "string" } } }, "GetApiLogisticsStopsByIdProofResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "stopId": { "type": "string" }, "tripId": { "type": "string" }, "outcome": { "type": "string" }, "receivedByName": { "type": "string" }, "receivedByRole": { "type": "string" }, "signatureAttachmentId": { "type": "string" }, "notes": { "type": "string" }, "capturedLatitude": { "type": "number" }, "capturedLongitude": { "type": "number" }, "capturedAccuracyM": { "type": "number" }, "distanceFromStopM": { "type": "number" }, "capturedAt": { "type": "string" }, "recordedAt": { "type": "string" }, "clockSkewMinutes": { "type": "integer" }, "driverId": { "type": "string" }, "driverName": { "type": "string" }, "deviceId": { "type": "string" }, "exceptionReasonCode": { "type": "string" }, "exceptionReasonLabel": { "type": "string" }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdProofResponsePhotosItem" } }, "strength": { "type": "string" }, "evidenceStatement": { "type": "string" }, "weaknesses": { "type": "array", "items": { "type": "string" } } } }, "GetApiLogisticsStopsByIdProofResponsePhotosItem": { "description": "Shared by 12 operations.", "type": "object", "properties": { "id": { "type": "string" }, "attachmentId": { "type": "string" }, "caption": { "type": "string" }, "sequence": { "type": "integer" } } }, "GetApiLogisticsStopsByIdResponse": { "description": "Shared by 9 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "sequence": { "type": "integer" }, "stopType": { "type": "string" }, "contactId": { "type": "string" }, "contactDisplayName": { "type": "string" }, "documentId": { "type": "string" }, "documentNumber": { "type": "string" }, "documentType": { "type": "string" }, "jobCardId": { "type": "string" }, "jobCardNumber": { "type": "string" }, "stockLocationId": { "type": "string" }, "address": { "type": "string" }, "suburb": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "contactName": { "type": "string" }, "contactPhone": { "type": "string" }, "instructions": { "type": "string" }, "windowFrom": { "type": "string", "format": "date" }, "windowTo": { "type": "string", "format": "date" }, "status": { "type": "string" }, "enRouteAt": { "type": "string" }, "arrivedAt": { "type": "string" }, "departedAt": { "type": "string" }, "arrivalLatitude": { "type": "number" }, "arrivalLongitude": { "type": "number" }, "arrivalAccuracyM": { "type": "number" }, "arrivalDistanceM": { "type": "number" }, "exceptionReasonCode": { "type": "string" }, "exceptionReasonLabel": { "type": "string" }, "exceptionNotes": { "type": "string" }, "stockPostedAt": { "type": "string" }, "stockWarnings": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponseLinesItem" } }, "proof": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponseProof" }, "collectable": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponseCollectable" }, "collection": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponseCollection" } } }, "GetApiLogisticsStopsByIdResponseCollectable": { "description": "Shared by 16 operations.", "type": "object", "properties": { "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "amountDue": { "type": "number" }, "foreignCurrency": { "type": "string" } } }, "GetApiLogisticsStopsByIdResponseCollection": { "description": "Shared by 17 operations.", "type": "object", "properties": { "id": { "type": "string" }, "stopId": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "customerName": { "type": "string" }, "paymentId": { "type": "string" }, "amount": { "type": "number" }, "method": { "type": "string" }, "reference": { "type": "string" }, "collectedAt": { "type": "string" }, "driverId": { "type": "string" }, "driverName": { "type": "string" }, "bankedAt": { "type": "string" }, "bankingId": { "type": "string" } } }, "GetApiLogisticsStopsByIdResponseLinesItem": { "description": "Shared by 10 operations.", "type": "object", "properties": { "id": { "type": "string" }, "invoiceLineId": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "qtyOrdered": { "type": "number" }, "qtyDelivered": { "type": "number" }, "qtyReturned": { "type": "number" }, "uom": { "type": "string" }, "batchNumber": { "type": "string" }, "stockMovementId": { "type": "string" }, "notes": { "type": "string" }, "shortfall": { "type": "number" }, "qtyLoaded": { "type": "number" }, "loadCheckedAt": { "type": "string" }, "service": { "type": "boolean" } } }, "GetApiLogisticsStopsByIdResponseProof": { "description": "Shared by 10 operations.", "type": "object", "properties": { "id": { "type": "string" }, "stopId": { "type": "string" }, "tripId": { "type": "string" }, "outcome": { "type": "string" }, "receivedByName": { "type": "string" }, "receivedByRole": { "type": "string" }, "signatureAttachmentId": { "type": "string" }, "notes": { "type": "string" }, "capturedLatitude": { "type": "number" }, "capturedLongitude": { "type": "number" }, "capturedAccuracyM": { "type": "number" }, "distanceFromStopM": { "type": "number" }, "capturedAt": { "type": "string" }, "recordedAt": { "type": "string" }, "clockSkewMinutes": { "type": "integer" }, "driverId": { "type": "string" }, "driverName": { "type": "string" }, "deviceId": { "type": "string" }, "exceptionReasonCode": { "type": "string" }, "exceptionReasonLabel": { "type": "string" }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdProofResponsePhotosItem" } }, "capturedInOffice": { "type": "boolean" }, "learnableLocation": { "type": "boolean" }, "strength": { "type": "string" }, "evidenceStatement": { "type": "string" }, "weaknesses": { "type": "array", "items": { "type": "string" } } } }, "GetApiLogisticsTrackingSettingsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "flushSeconds": { "type": "integer" }, "minSeconds": { "type": "integer" }, "maxSeconds": { "type": "integer" } } }, "GetApiLogisticsTripsByIdInspectionsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tripId": { "type": "string" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "driverName": { "type": "string" }, "state": { "type": "string" }, "stateLabel": { "type": "string" }, "answers": { "type": "array", "items": { "$ref": "#/components/schemas/PostDriverApiV1TripsByIdStartRequestInspectionAnswersItem" } }, "failedItems": { "type": "array", "items": { "type": "string" } }, "capturedAt": { "type": "string" }, "recordedAt": { "type": "string" }, "decidedAt": { "type": "string" }, "decidedByName": { "type": "string" } } }, "GetApiLogisticsUnassignedResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "documentId": { "type": "string" }, "documentNumber": { "type": "string" }, "documentType": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "deliveryDate": { "type": "string", "format": "date" }, "address": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "lineCount": { "type": "integer" }, "totalQty": { "type": "number" }, "total": { "type": "number" }, "currency": { "type": "string" } } }, "GetApiMrpBatchTraceResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "direction": { "type": "string" }, "rootBatchId": { "type": "string" }, "rootBatchNumber": { "type": "string" }, "rootProductName": { "type": "string" }, "rootSku": { "type": "string" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpBatchTraceResponseNodesItem" } }, "maxDepth": { "type": "integer" }, "truncated": { "type": "boolean" }, "unaccountedQty": { "type": "number" } } }, "GetApiMrpBatchTraceResponseNodesItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "batchId": { "type": "string" }, "batchNumber": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "qty": { "type": "number" }, "unitCost": { "type": "number" }, "supplier": { "type": "string" }, "expiryDate": { "type": "string", "format": "date" }, "workOrderId": { "type": "string" }, "woNumber": { "type": "string" }, "workOrderStatus": { "type": "string" }, "consumedAt": { "type": "string" }, "depth": { "type": "integer" }, "kind": { "type": "string" } } }, "GetApiMrpForecastSuggestionResponseMonthsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "month": { "type": "string", "format": "date" }, "qty": { "type": "number" } } }, "GetApiMrpPeriodicChecksResponseItemsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "planId": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "minValue": { "type": "number" }, "maxValue": { "type": "number" }, "unit": { "type": "string" }, "workCentreCode": { "type": "null" }, "slotStart": { "type": "string" }, "dueBy": { "type": "string" }, "result": { "type": "string" }, "measuredValue": { "type": "number" }, "notes": { "type": "null" }, "recordedByName": { "type": "string" }, "recordedAt": { "type": "string" }, "missed": { "type": "boolean" } } }, "GetApiMrpRoutingsOperationsByOpIdChecksResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpRoutingsOperationsByOpIdChecksResponseItemsItem" } } } }, "GetApiMrpRoutingsOperationsByOpIdChecksResponseItemsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "minValue": { "type": "number" }, "maxValue": { "type": "number" }, "unit": { "type": "string" }, "sequenceNo": { "type": "integer" } } }, "GetApiMrpRunsResponseItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "runNumber": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "horizonStart": { "type": "string", "format": "date" }, "horizonEnd": { "type": "string", "format": "date" }, "bucketDays": { "type": "integer" }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "includeSafetyStock": { "type": "boolean" }, "includeOnOrder": { "type": "boolean" }, "netOffPlannedOrders": { "type": "boolean" }, "supersedesRunId": { "type": "string" }, "plannedOrderCount": { "type": "integer" }, "purchaseOrderCount": { "type": "integer" }, "productionOrderCount": { "type": "integer" }, "exceptionCount": { "type": "integer" }, "demandLineCount": { "type": "integer" }, "productCount": { "type": "integer" }, "maxLevel": { "type": "integer" }, "totalPlannedValue": { "type": "number" }, "unplannedDemandCount": { "type": "integer" }, "convertedCount": { "type": "integer" }, "durationMs": { "type": "integer" }, "errorText": { "type": "string" }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" }, "createdByName": { "type": "string" }, "kind": { "type": "string" }, "whatIfDemandPercent": { "type": "integer" }, "whatIfProductId": { "type": "string" }, "whatIfProductName": { "type": "string" }, "whatIfExtraLeadDays": { "type": "integer" } } }, "GetApiMrpScrapAnalysisResponseByReasonItem": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "qty": { "type": "number" }, "cost": { "type": "number" }, "eventCount": { "type": "integer" }, "controllable": { "type": "boolean" }, "sharePercent": { "type": "number" } } }, "GetApiMrpScrapReasonsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "controllable": { "type": "boolean" }, "active": { "type": "boolean" }, "isCustom": { "type": "boolean" }, "id": { "type": "string" } } }, "GetApiMrpSupplyRulesResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "sourceLocationId": { "type": "string" }, "sourceLocationName": { "type": "string" }, "leadDays": { "type": "integer" } } }, "GetApiMrpWorkersResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "workers": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpWorkersResponseWorkersItem" } } } }, "GetApiMrpWorkersResponseWorkersItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "labourRatePerHour": { "type": "number" } } }, "GetApiOauthAppsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "clientId": { "type": "string" }, "redirectUris": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" } } }, "GetApiPaymentGatewaysPayfastCredentialsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "configured": { "type": "boolean" }, "source": { "type": "string" }, "merchantId": { "type": "string" }, "merchantKeyHint": { "type": "string" }, "hasPassphrase": { "type": "boolean" }, "sandbox": { "type": "boolean" }, "active": { "type": "boolean" }, "companyScoped": { "type": "boolean" }, "updatedAt": { "type": "string" } } }, "GetApiPaymentGatewaysYocoCredentialsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "configured": { "type": "boolean" }, "source": { "type": "string" }, "secretKeyHint": { "type": "string" }, "hasWebhookSecret": { "type": "boolean" }, "live": { "type": "boolean" }, "active": { "type": "boolean" }, "companyScoped": { "type": "boolean" }, "setupBlocker": { "type": "string" }, "webhookUrl": { "type": "string" }, "updatedAt": { "type": "string" } } }, "GetApiPayrollDocumentExpiriesResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollDocumentExpiriesResponseDocumentsItem" } }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollDocumentExpiriesResponseKindsItem" } }, "expiredCount": { "type": "integer" }, "expiringSoonCount": { "type": "integer" }, "attentionSummary": { "type": "string" }, "warnDays": { "type": "integer" } } }, "GetApiPayrollDocumentExpiriesResponseDocumentsItem": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "kind": { "type": "string" }, "kindLabel": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "issuedOn": { "type": "string", "format": "date" }, "expiresOn": { "type": "string", "format": "date" }, "expiryStatus": { "type": "string" }, "expirySentence": { "type": "string" }, "daysUntilExpiry": { "type": "integer" }, "needsAttention": { "type": "boolean" }, "source": { "type": "string" }, "verifiedAt": { "type": "string" }, "verifiedByName": { "type": "string" }, "fileUrl": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "createdAt": { "type": "string" } } }, "GetApiPayrollDocumentExpiriesResponseKindsItem": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "consequence": { "type": "string" }, "expires": { "type": "boolean" }, "employeeMayUpload": { "type": "boolean" } } }, "GetApiPayrollEmp501Response": { "description": "Shared by 2 operations.", "type": "object", "properties": { "taxYear": { "type": "string" }, "months": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollEmp501ResponseMonthsItem" } }, "interimPaye": { "type": "number" }, "interimUif": { "type": "number" }, "interimSdl": { "type": "number" }, "interimEti": { "type": "number" }, "interimTotal": { "type": "number" }, "interimPaid": { "type": "number" }, "annualPaye": { "type": "number" }, "annualUif": { "type": "number" }, "annualSdl": { "type": "number" }, "annualEti": { "type": "number" }, "annualTotal": { "type": "number" }, "annualPaid": { "type": "number" } } }, "GetApiPayrollEmp501ResponseMonthsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "month": { "type": "string" }, "paye": { "type": "number" }, "uif": { "type": "number" }, "sdl": { "type": "number" }, "eti": { "type": "number" }, "total": { "type": "number" }, "paid": { "type": "number" } } }, "GetApiPayrollEmployeesByEmployeeIdEarningsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "basicSalary": { "type": "number" }, "earnings": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollEmployeesByEmployeeIdEarningsResponseEarningsItem" } }, "available": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollEarningTypesResponse" } } } }, "GetApiPayrollEmployeesByEmployeeIdEarningsResponseEarningsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "earningTypeId": { "type": "string" }, "name": { "type": "string" }, "sarsCode": { "type": "string" }, "sarsLabel": { "type": "string" }, "calculation": { "type": "string" }, "unitLabel": { "type": "string" }, "amount": { "type": "number" }, "percent": { "type": "number" }, "rate": { "type": "number" }, "units": { "type": "number" }, "usingDefault": { "type": "boolean" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" }, "taxable": { "type": "boolean" }, "preview": { "type": "number" }, "working": { "type": "string" } } }, "GetApiPayrollEmployeesByIdPortalLinkResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "active": { "type": "boolean" }, "issuedAt": { "type": "string" }, "expiresAt": { "type": "string" }, "revokedAt": { "type": "string" }, "lastAccessedAt": { "type": "string" }, "accessCount": { "type": "integer" } } }, "GetApiPayrollEtiResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "monthStart": { "type": "string", "format": "date" }, "monthEnd": { "type": "string", "format": "date" }, "monthLabel": { "type": "string" }, "bandTable": { "type": "string" }, "employees": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollEtiResponseEmployeesItem" } }, "qualifyingCount": { "type": "integer" }, "calculatedTotal": { "type": "number" }, "unclaimedCount": { "type": "integer" }, "recomputeCount": { "type": "integer" }, "claim": { "$ref": "#/components/schemas/GetApiPayrollEtiResponseClaim" }, "estimated": { "type": "boolean" }, "employer": { "$ref": "#/components/schemas/GetApiPayrollEtiResponseEmployer" } } }, "GetApiPayrollEtiResponseClaim": { "description": "Shared by 3 operations.", "type": "object", "properties": { "monthEnd": { "type": "string", "format": "date" }, "broughtForward": { "type": "number" }, "calculated": { "type": "number" }, "available": { "type": "number" }, "utilised": { "type": "number" }, "grossPaye": { "type": "number" }, "netPaye": { "type": "number" }, "carriedForward": { "type": "number" }, "ringFencedForRefund": { "type": "number" } } }, "GetApiPayrollEtiResponseEmployeesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeNumber": { "type": "string" }, "employeeName": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date" }, "startDate": { "type": "string", "format": "date" }, "ageAtMonthEnd": { "type": "integer" }, "qualifies": { "type": "boolean" }, "qualifyingMonth": { "type": "integer" }, "monthsUsed": { "type": "integer" }, "firstYear": { "type": "boolean" }, "amount": { "type": "number" }, "reason": { "type": "string" }, "qualifiesButUnclaimed": { "type": "boolean" }, "remuneration": { "type": "number" }, "basis": { "type": "string" }, "minimumWageMonthly": { "type": "number" }, "noWageRegulatingMeasure": { "type": "boolean" }, "monthsClaimedBeforeLedgr": { "type": "integer" }, "exclusion": { "type": "string" }, "ordinaryHoursMonthly": { "type": "number" }, "staleVsCapturedFacts": { "type": "string" }, "hoursWorked": { "type": "number" }, "hoursSource": { "type": "string" }, "sezCode": { "type": "string" } } }, "GetApiPayrollEtiResponseEmployer": { "description": "Shared by 3 operations.", "type": "object", "properties": { "sezQualifyingCompany": { "type": "boolean" }, "ineligibleEmployer": { "type": "string" }, "ineligibleReason": { "type": "string" } } }, "GetApiPayrollPeriodsByIdEmp201Response": { "description": "Shared by 2 operations.", "type": "object", "properties": { "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "totalPaye": { "type": "number" }, "totalUif": { "type": "number" }, "totalSdl": { "type": "number" }, "totalEti": { "type": "number" }, "totalEtiCalculated": { "type": "number" }, "payeAfterEti": { "type": "number" }, "totalPayable": { "type": "number" }, "employeeCount": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollPeriodsByIdEmp201ResponseLinesItem" } } } }, "GetApiPayrollPeriodsByIdEmp201ResponseLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "paye": { "type": "number" }, "uif": { "type": "number" }, "sdl": { "type": "number" } } }, "GetApiPayrollPeriodsByIdInputsResponseItemsItem": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "employeeId": { "type": "string" }, "earningTypeId": { "type": "string" }, "earningTypeName": { "type": "string" }, "units": { "type": "number" }, "amount": { "type": "number" }, "sourceKind": { "type": "string" }, "sourceRef": { "type": "string" }, "note": { "type": "string" } } }, "GetApiPayrollPeriodsByIdJournalResponseLinesItem": { "type": "object", "properties": { "accountCode": { "type": "string" }, "accountName": { "type": "string" }, "description": { "type": "string" }, "debit": { "type": "number" }, "credit": { "type": "number" } } }, "GetApiPayrollSettingsResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "design": { "$ref": "#/components/schemas/GetApiPayrollSettingsResponseDesign" }, "leave": { "$ref": "#/components/schemas/PutApiPayrollSettingsRequestLeave" }, "logoUrl": { "type": "string" }, "logoInheritedFromInvoices": { "type": "boolean" }, "presets": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollSettingsResponsePresetsItem" } }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollSettingsResponseSectionsItem" } }, "leaveCarryOverNote": { "type": "string" }, "leaveIsStatutoryMinimum": { "type": "boolean" }, "banking": { "$ref": "#/components/schemas/PutApiPayrollSettingsRequestBanking" }, "payingBankAccountOptions": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollSettingsResponsePayingBankAccountOptionsItem" } } } }, "GetApiPayrollSettingsResponseDesign": { "description": "Shared by 4 operations.", "type": "object", "properties": { "title": { "type": "string" }, "accentHex": { "type": "string" }, "showLogo": { "type": "boolean" }, "logoAttachmentId": { "type": "string" }, "logoScalePercent": { "type": "integer" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiPayrollSettingsRequestDesignSectionsItem" } }, "labels": { "$ref": "#/components/schemas/GetApiPayrollSettingsResponseDesignLabels" }, "bankAccount": { "type": "string" }, "density": { "type": "string" }, "showTaxNumber": { "type": "boolean" }, "showIdNumber": { "type": "boolean" }, "message": { "type": "string" }, "footerText": { "type": "string" }, "presetId": { "type": "string" } } }, "GetApiPayrollSettingsResponseDesignLabels": { "description": "Shared by 6 operations.", "type": "object", "properties": { "key": { "type": "string" } } }, "GetApiPayrollSettingsResponsePayingBankAccountOptionsItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "accountMasked": { "type": "string" }, "bankName": { "type": "string" } } }, "GetApiPayrollSettingsResponsePresetsItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "forWhom": { "type": "string" } } }, "GetApiPayrollSettingsResponseSectionsItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" }, "bceaReference": { "type": "string" } } }, "GetApiPayrollTakeOnByEmployeeIdEtiMonthsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "employeeId": { "type": "string" }, "taxYearEndYear": { "type": "integer" }, "months": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiPayrollTakeOnByEmployeeIdEtiMonthsRequestMonthsItem" } } } }, "GetApiPayrollTakeOnColumnsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "header": { "type": "string" }, "meaning": { "type": "string" } } }, "GetApiPayrollTakeOnResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "taxYearEndYear": { "type": "integer" }, "taxYear": { "type": "string" }, "midYearSwitch": { "type": "boolean" }, "firstLedgrPayDate": { "type": "string", "format": "date" }, "employees": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollTakeOnResponseEmployeesItem" } }, "statedCount": { "type": "integer" }, "employeeCount": { "type": "integer" }, "totalRemuneration": { "type": "number" }, "totalPaye": { "type": "number" }, "totalUif": { "type": "number" }, "totalSdl": { "type": "number" }, "blockingCount": { "type": "integer" }, "warningCount": { "type": "integer" } } }, "GetApiPayrollTakeOnResponseEmployeesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeNumber": { "type": "string" }, "employeeName": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "stated": { "type": "boolean" }, "taxYearEndYear": { "type": "integer" }, "taxYear": { "type": "string" }, "figures": { "$ref": "#/components/schemas/GetApiPayrollTakeOnResponseEmployeesItemFigures" }, "provenance": { "$ref": "#/components/schemas/GetApiPayrollTakeOnResponseEmployeesItemProvenance" }, "issues": { "type": "array", "items": { "type": "object" } }, "derivedPeriodsWorked": { "type": "integer" }, "periodsRunInLedgr": { "type": "integer" } } }, "GetApiPayrollTakeOnResponseEmployeesItemFigures": { "description": "Shared by 3 operations.", "type": "object", "properties": { "taxYearEndYear": { "type": "integer" }, "periodsWorked": { "type": "integer" }, "remuneration": { "type": "number" }, "paye": { "type": "number" }, "annualPayments": { "type": "number" }, "payeOnAnnualPayments": { "type": "number" }, "uifEmployee": { "type": "number" }, "uifEmployer": { "type": "number" }, "sdl": { "type": "number" }, "retirementEmployee": { "type": "number" }, "retirementEmployer": { "type": "number" }, "medicalEmployee": { "type": "number" }, "medicalEmployer": { "type": "number" }, "medicalTaxCredit": { "type": "number" }, "fringeBenefits": { "type": "number" }, "overtime": { "type": "number" }, "commission": { "type": "number" }, "travelAllowance": { "type": "number" }, "otherAllowances": { "type": "number" }, "fringeAccommodation": { "type": "number" }, "fringeMedicalCosts": { "type": "number" } } }, "GetApiPayrollTakeOnResponseEmployeesItemProvenance": { "description": "Shared by 2 operations.", "type": "object", "properties": { "source": { "type": "string" }, "sourceLabel": { "type": "string" }, "capturedAt": { "type": "string" }, "capturedBy": { "type": "string" }, "note": { "type": "string" }, "method": { "type": "string" } } }, "GetApiPayrollYtdResponseRowsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeNumber": { "type": "string" }, "employeeName": { "type": "string" }, "costCentre": { "type": "string" }, "amounts": { "$ref": "#/components/schemas/GetApiPayrollYtdResponseTotals" } } }, "GetApiPayrollYtdResponseTotals": { "description": "Shared by 4 operations.", "type": "object", "properties": { "key": { "type": "number" } } }, "GetApiPayslipsByIdResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "periodId": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "payDate": { "type": "string", "format": "date" }, "basicSalary": { "type": "number" }, "travelAllowance": { "type": "number" }, "overtime": { "type": "number" }, "commission": { "type": "number" }, "bonus": { "type": "number" }, "otherAllowances": { "type": "number" }, "grossSalary": { "type": "number" }, "pensionContribution": { "type": "number" }, "medicalAidContribution": { "type": "number" }, "employerRetirement": { "type": "number" }, "employerMedical": { "type": "number" }, "thirdPartyDeductions": { "type": "number" }, "taxableRemuneration": { "type": "number" }, "travelInclusionRate": { "type": "number" }, "payeTax": { "type": "number" }, "uifEmployee": { "type": "number" }, "uifEmployer": { "type": "number" }, "sdl": { "type": "number" }, "netPay": { "type": "number" }, "ytdGross": { "type": "number" }, "ytdPaye": { "type": "number" }, "hoursWorked": { "type": "number" }, "etiHoursSource": { "type": "string" }, "etiAmount": { "type": "number" }, "etiReason": { "type": "string" }, "catchUpPaye": { "type": "number" }, "catchUpNotice": { "type": "string" }, "deductionLines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayslipsByIdResponseDeductionLinesItem" } }, "fringeBenefitsOtherRemuneration": { "type": "number" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "GetApiPayslipsByIdResponseDeductionLinesItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "beneficiaryName": { "type": "string" }, "reference": { "type": "string" }, "employeeAmount": { "type": "number" }, "employerAmount": { "type": "number" } } }, "GetApiPractitionerAccountTemplatesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "promise": { "type": "string" }, "templates": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPractitionerAccountTemplatesResponseTemplatesItem" } } } }, "GetApiPractitionerAccountTemplatesResponseTemplatesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "lineCount": { "type": "integer" }, "sourceName": { "type": "string" }, "capturedAt": { "type": "string" }, "summary": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPractitionerAccountTemplatesResponseTemplatesItemLinesItem" } } } }, "GetApiPractitionerAccountTemplatesResponseTemplatesItemLinesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "accountType": { "type": "string" }, "normalBalance": { "type": "string" }, "accountSubtype": { "type": "string" }, "parentCode": { "type": "string" }, "cashFlowSection": { "type": "string" }, "isContra": { "type": "boolean" } } }, "GetApiPractitionerClientsByIdAddonsResponseHeldItem": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "blurb": { "type": "string" }, "unitPriceMonthly": { "type": "number" }, "quantity": { "type": "integer" }, "monthlyPrice": { "type": "number" }, "seatsPerUnit": { "type": "integer" }, "unlocks": { "type": "array", "items": { "type": "string" } }, "maxQuantity": { "type": "integer" }, "unitLabel": { "type": "string" }, "requiresNote": { "type": "string" }, "proRataCents": { "type": "integer" }, "proRataNote": { "type": "string" }, "pendingOrderId": { "type": "string" }, "pendingCheckoutUrl": { "type": "string" }, "pendingAmountCents": { "type": "integer" } } }, "GetApiPractitionerClientsByIdFieldsResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "summary": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdFieldsResponseFieldsItem" } } } }, "GetApiPractitionerClientsByIdFieldsResponseFieldsItem": { "description": "Shared by 5 operations.", "type": "object", "properties": { "fieldId": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "value": { "type": "string" }, "display": { "type": "string" } } }, "GetApiPractitionerClientsByIdStaffResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "inviteeEmail": { "type": "string" }, "inviteeName": { "type": "string" }, "assigned": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdStaffResponseRosterItem" } }, "roster": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdStaffResponseRosterItem" } }, "clientIsTold": { "type": "string" } } }, "GetApiPractitionerClientsByIdStaffResponseRosterItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "roleName": { "type": "string" }, "isSelf": { "type": "boolean" } } }, "GetApiPractitionerClientsByIdTaxReferencesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "vatNumber": { "type": "string" }, "vatCategory": { "type": "string" }, "taxNumber": { "type": "string" }, "payeNumber": { "type": "string" }, "uifNumber": { "type": "string" }, "sdlNumber": { "type": "string" } } }, "GetApiPractitionerDirectoryListingResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "exists": { "type": "boolean" }, "optedIn": { "type": "boolean" }, "displayName": { "type": "string" }, "town": { "type": "string" }, "province": { "type": "string" }, "services": { "type": "array", "items": { "type": "string" } }, "contactEmail": { "type": "string" }, "website": { "type": "string" }, "hidden": { "type": "boolean" }, "hiddenReason": { "type": "string" }, "listed": { "type": "boolean" }, "eligible": { "type": "boolean" }, "summary": { "type": "string" } } }, "GetApiPractitionerJobsResponseBoardsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "boardId": { "type": "string" }, "name": { "type": "string" } } }, "GetApiPractitionerPayoutBankDetailsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "configured": { "type": "boolean" }, "bankName": { "type": "string" }, "accountHolder": { "type": "string" }, "accountNumberMasked": { "type": "string" }, "branchCode": { "type": "string" } } }, "GetApiPractitionerProfessionalRegistrationResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "status": { "type": "string" }, "body": { "type": "string" }, "bodyLabel": { "type": "string" }, "membershipNumber": { "type": "string" }, "decisionNote": { "type": "null" }, "submittedAt": { "type": "string" }, "decidedAt": { "type": "null" }, "payoutHeld": { "type": "boolean" }, "rungLabel": { "type": "string" }, "rungPercent": { "type": "number" }, "summary": { "type": "string" } } }, "GetApiPractitionerQueriesByIdFilesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "subjectType": { "type": "string" }, "subjectLabel": { "type": "string" }, "question": { "type": "string" }, "kind": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "status": { "type": "string" }, "statusWord": { "type": "string" }, "clientNote": { "type": "string" }, "fileCount": { "type": "integer" }, "priority": { "type": "string" }, "askedByEmail": { "type": "string" }, "createdAt": { "type": "string" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPractitionerQueriesByIdFilesResponseFilesItem" } } } }, "GetApiPractitionerQueriesByIdFilesResponseFilesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "caption": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "uploadedAt": { "type": "string" }, "uploadedByName": { "type": "string" }, "url": { "type": "string" } } }, "GetApiPractitionerReportTemplatesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPractitionerReportTemplatesResponseTemplatesItem" } }, "promise": { "type": "string" } } }, "GetApiPractitionerReportTemplatesResponseTemplatesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "actionIds": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "createdAt": { "type": "string" } } }, "GetApiPractitionerVisitFilingProfileResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "companyId": { "type": "string" }, "companyName": { "type": "string" }, "vatCategory": { "type": "string" }, "fiscalYearEndMonth": { "type": "integer" }, "fiscalYearEndName": { "type": "string" } } }, "GetApiProcurementCodingOptionsResponseAccountsItem": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" } } }, "GetApiProcurementMatchesResponseItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "billId": { "type": "string" }, "billNumber": { "type": "string" }, "vendorName": { "type": "string" }, "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "goodsReceiptId": { "type": "string" }, "goodsReceiptNumber": { "type": "string" }, "status": { "type": "string" }, "poTotal": { "type": "number" }, "receiptTotal": { "type": "number" }, "invoiceTotal": { "type": "number" }, "priceVariance": { "type": "number" }, "priceVariancePercent": { "type": "number" }, "qtyVariance": { "type": "number" }, "toleranceAmount": { "type": "number" }, "tolerancePercent": { "type": "number" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementMatchesResponseItemLinesItem" } }, "matchedAt": { "type": "string" }, "resolvedAt": { "type": "string" }, "resolvedByName": { "type": "string" }, "resolutionNote": { "type": "string" }, "blocksPayment": { "type": "boolean" }, "matchBasis": { "type": "string" }, "overBilledQty": { "type": "number" } } }, "GetApiProcurementMatchesResponseItemLinesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "description": { "type": "string" }, "qtyOrdered": { "type": "number" }, "qtyReceived": { "type": "number" }, "qtyBilled": { "type": "number" }, "lineMatched": { "type": "boolean" }, "priceOrdered": { "type": "number" }, "priceReceived": { "type": "number" }, "priceVariance": { "type": "number" }, "qtyVariance": { "type": "number" }, "withinTolerance": { "type": "boolean" }, "note": { "type": "string" } } }, "GetApiProcurementReplenishmentResponseSkippedItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "name": { "type": "string" }, "reason": { "type": "string" } } }, "GetApiProcurementRequisitionsByIdBudgetImpactResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "budgetId": { "type": "string" }, "budgetName": { "type": "string" }, "policy": { "type": "string" }, "budget": { "type": "number" }, "actual": { "type": "number" }, "committed": { "type": "number" }, "thisPurchase": { "type": "number" }, "available": { "type": "number" }, "remainingAfter": { "type": "number" }, "overBy": { "type": "number" }, "exceeded": { "type": "boolean" }, "needsExtraApproval": { "type": "boolean" }, "summary": { "type": "string" }, "approvalStatus": { "type": "string" }, "canDecide": { "type": "boolean" }, "decisionComment": { "type": "string" } } }, "GetApiProcurementRequisitionsByIdResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "requisitionNumber": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "requestedByName": { "type": "string" }, "requestedFor": { "type": "string" }, "requiredDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "estimatedTotal": { "type": "number" }, "budgetAccountId": { "type": "string" }, "budgetAccountName": { "type": "string" }, "budgetRemaining": { "type": "number" }, "costCentreId": { "type": "string" }, "costCentreName": { "type": "string" }, "mrpRunId": { "type": "string" }, "mrpRunNumber": { "type": "string" }, "justification": { "type": "string" }, "notes": { "type": "string" }, "lineCount": { "type": "integer" }, "submittedAt": { "type": "string" }, "approvedAt": { "type": "string" }, "rejectedAt": { "type": "string" }, "rejectionReason": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementRequisitionsByIdResponseLinesItem" } }, "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementRequisitionsByIdResponseApprovalsItem" } }, "currentStep": { "type": "integer" }, "awaitingMe": { "type": "boolean" }, "purchaseOrderIds": { "type": "array", "items": { "type": "string" } } } }, "GetApiProcurementRequisitionsByIdResponseApprovalsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "stepNo": { "type": "integer" }, "approverLabel": { "type": "string" }, "approverRoleId": { "type": "string" }, "approverUserId": { "type": "string" }, "status": { "type": "string" }, "decidedByName": { "type": "string" }, "decidedAt": { "type": "string" }, "comment": { "type": "string" }, "canDecide": { "type": "boolean" } } }, "GetApiProcurementRequisitionsByIdResponseLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "lineNumber": { "type": "integer" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "description": { "type": "string" }, "qty": { "type": "number" }, "unit": { "type": "string" }, "requiredDate": { "type": "string", "format": "date" }, "estimatedUnitPrice": { "type": "number" }, "estimatedTotal": { "type": "number" }, "suggestedSupplierId": { "type": "string" }, "suggestedSupplierName": { "type": "string" }, "plannedOrderId": { "type": "string" }, "status": { "type": "string" }, "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "notes": { "type": "string" }, "approvedVendorCount": { "type": "integer" } } }, "GetApiProcurementRfqsByIdResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "rfqNumber": { "type": "string" }, "title": { "type": "string" }, "requisitionId": { "type": "string" }, "requisitionNumber": { "type": "string" }, "status": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "responseDueDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "deliveryAddress": { "type": "string" }, "terms": { "type": "string" }, "notes": { "type": "string" }, "awardedSupplierId": { "type": "string" }, "awardedSupplierName": { "type": "string" }, "awardedQuoteId": { "type": "string" }, "awardReason": { "type": "string" }, "awardedAt": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementRfqsByIdResponseLinesItem" } }, "suppliers": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementRfqsByIdResponseSuppliersItem" } }, "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementRfqsByIdResponseQuotesItem" } }, "invitedCount": { "type": "integer" }, "respondedCount": { "type": "integer" }, "lowestQuoteTotal": { "type": "number" } } }, "GetApiProcurementRfqsByIdResponseLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "lineNumber": { "type": "integer" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "description": { "type": "string" }, "qty": { "type": "number" }, "unit": { "type": "string" }, "requiredDate": { "type": "string", "format": "date" }, "requisitionLineId": { "type": "string" }, "quotedPrices": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementRfqsByIdResponseLinesItemQuotedPricesItem" } } } }, "GetApiProcurementRfqsByIdResponseLinesItemQuotedPricesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "quoteId": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "unitPrice": { "type": "number" }, "lineTotal": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "isLowest": { "type": "boolean" } } }, "GetApiProcurementRfqsByIdResponseQuotesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "rfqId": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "quoteNumber": { "type": "string" }, "quoteDate": { "type": "string", "format": "date" }, "validUntil": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "subtotal": { "type": "number" }, "vatAmount": { "type": "number" }, "total": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "paymentTermsDays": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementRfqsByIdResponseQuotesItemLinesItem" } }, "isLowest": { "type": "boolean" } } }, "GetApiProcurementRfqsByIdResponseQuotesItemLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "rfqLineId": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "qty": { "type": "number" }, "unitPrice": { "type": "number" }, "lineTotal": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "notes": { "type": "string" } } }, "GetApiProcurementRfqsByIdResponseSuppliersItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "status": { "type": "string" }, "contactEmail": { "type": "string" }, "sentAt": { "type": "string" }, "respondedAt": { "type": "string" }, "quoteId": { "type": "string" }, "quoteTotal": { "type": "number" } } }, "GetApiProcurementSupplierDocumentsPolicyResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "expires": { "type": "boolean" }, "consequence": { "type": "string" }, "required": { "type": "boolean" }, "onExpiry": { "type": "string", "format": "date" } } }, "GetApiProcurementSupplierRegistrationLinkResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "enabled": { "type": "boolean" }, "url": { "type": "string" }, "token": { "type": "string" }, "intro": { "type": "string" }, "requiredDocuments": { "type": "array", "items": { "type": "string" } }, "unavailableReason": { "type": "string" } } }, "GetApiProcurementSuppliersByContactIdPunchoutResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "contactId": { "type": "string" }, "protocol": { "type": "string" }, "setupUrl": { "type": "string" }, "fromIdentity": { "type": "string" }, "toIdentity": { "type": "string" }, "senderIdentity": { "type": "string" }, "username": { "type": "string" }, "hasSecret": { "type": "boolean" }, "active": { "type": "boolean" }, "configured": { "type": "boolean" } } }, "GetApiProcurementVendorsByIdPriceBreaksResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "minQty": { "type": "number" }, "unitPrice": { "type": "number" }, "note": { "type": "string" } } }, "GetApiPurchaseOrdersByIdReceiptsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "receiptNumber": { "type": "string" }, "receiptDate": { "type": "string", "format": "date" }, "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "deliveryNoteRef": { "type": "string" }, "notes": { "type": "string" }, "billId": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPurchaseOrdersByIdReceiptsResponseItemLinesItem" } }, "total": { "type": "number" } } }, "GetApiPurchaseOrdersByIdReceiptsResponseItemLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "qtyReceived": { "type": "number" }, "unitCost": { "type": "number" }, "lineTotal": { "type": "number" }, "batchNumber": { "type": "string" } } }, "GetApiPurchaseOrdersByIdResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "supplierName": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "expectedDate": { "type": "string", "format": "date" }, "status": { "type": "string" }, "total": { "type": "number" }, "outstandingValue": { "type": "number" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPurchaseOrdersByIdResponseLinesItem" } }, "billId": { "type": "string" }, "receiptCount": { "type": "integer" } } }, "GetApiPurchaseOrdersByIdResponseLinesItem": { "description": "Shared by 5 operations.", "type": "object", "properties": { "lineId": { "type": "string" }, "description": { "type": "string" }, "productId": { "type": "string" }, "qtyOrdered": { "type": "number" }, "qtyReceived": { "type": "number" }, "qtyOutstanding": { "type": "number" }, "unitPrice": { "type": "number" } } }, "GetApiPurchaseOrdersInspectionProductsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "inspectOnReceipt": { "type": "boolean" } } }, "GetApiPurchaseOrdersReceiptsByReceiptIdResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "receiptNumber": { "type": "string" }, "receiptDate": { "type": "string", "format": "date" }, "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "deliveryNoteRef": { "type": "string" }, "billId": { "type": "string" }, "billNumber": { "type": "string" }, "billStatus": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPurchaseOrdersReceiptsByReceiptIdResponseLinesItem" } }, "returns": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPurchaseOrdersReturnsResponseItem" } } } }, "GetApiPurchaseOrdersReceiptsByReceiptIdResponseLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "poLineId": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "qtyReceived": { "type": "number" }, "unitCost": { "type": "number" }, "batchNumber": { "type": "string" }, "expiryDate": { "type": "string", "format": "date" }, "qtyReturned": { "type": "number" }, "returnable": { "type": "number" }, "inspectionStatus": { "type": "string" }, "qtyAccepted": { "type": "number" }, "qtyRejected": { "type": "number" }, "rejectionReason": { "type": "string" }, "awaitingInspection": { "type": "number" }, "rejectedNotReturned": { "type": "number" }, "qtyPrecision": { "type": "integer" }, "vatRate": { "type": "number" } } }, "GetApiPurchaseOrdersResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "asOf": { "type": "string" }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPurchaseOrdersByIdResponse" } }, "totalOutstanding": { "type": "number" }, "openOrderCount": { "type": "integer" } } }, "GetApiPurchaseOrdersReturnsResponseItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "returnNumber": { "type": "string" }, "returnDate": { "type": "string", "format": "date" }, "receiptId": { "type": "string" }, "receiptNumber": { "type": "string" }, "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "supplierName": { "type": "string" }, "reason": { "type": "string" }, "resolution": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPurchaseOrdersReturnsResponseItemLinesItem" } }, "creditNoteId": { "type": "string" }, "creditNoteNumber": { "type": "string" }, "creditTotal": { "type": "number" }, "notice": { "type": "string" } } }, "GetApiPurchaseOrdersReturnsResponseItemLinesItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "receiptLineId": { "type": "string" }, "description": { "type": "string" }, "qty": { "type": "number" }, "unitCost": { "type": "number" }, "creditValue": { "type": "number" }, "stockValue": { "type": "number" } } }, "GetApiReconciliationByIdReportResponseClearedItem": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "reference": { "type": "null" }, "amount": { "type": "number" }, "matchedTo": { "type": "string" } } }, "GetApiReconciliationByIdResponse": { "description": "Shared by 9 operations.", "type": "object", "properties": { "id": { "type": "string" }, "bankAccountId": { "type": "string" }, "statementBalance": { "type": "number" }, "openingBalance": { "type": "number" }, "clearedBalance": { "type": "number" }, "difference": { "type": "number" }, "clearedIds": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "GetApiRecurringByIdLeaseDepositResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "leaseId": { "type": "string" }, "required": { "type": "number" }, "held": { "type": "number" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiRecurringByIdLeaseDepositResponseMovementsItem" } } } }, "GetApiRecurringByIdLeaseDepositResponseMovementsItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "amount": { "type": "number" }, "on": { "type": "string", "format": "date" }, "method": { "type": "string" }, "reference": { "type": "string" }, "journalId": { "type": "string" }, "invoiceId": { "type": "string" } } }, "GetApiRecurringByIdLeaseResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "scheduleId": { "type": "string" }, "propertyId": { "type": "string" }, "propertyName": { "type": "string" }, "unit": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "rent": { "type": "number" }, "frequency": { "type": "string" }, "escalationPercent": { "type": "number" }, "escalationDate": { "type": "string", "format": "date" }, "escalationMonths": { "type": "integer" }, "nextRent": { "type": "number" }, "deposit": { "type": "number" } } }, "GetApiReminderConfigsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "enabled": { "type": "boolean" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiReminderConfigsRequestStepsItem" } }, "message": { "type": "string" } } }, "GetApiRentalContractsByIdDepositResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "contractId": { "type": "string" }, "held": { "type": "number" }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiRentalContractsByIdDepositResponseMovementsItem" } }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRentalContractsByIdDepositLinkResponse" } } } }, "GetApiRentalContractsByIdDepositResponseMovementsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "amount": { "type": "number" }, "on": { "type": "string", "format": "date" }, "method": { "type": "string" }, "reference": { "type": "string" }, "invoiceId": { "type": "string" }, "journalId": { "type": "string" }, "awaitingPayout": { "type": "boolean" } } }, "GetApiRentalContractsByIdResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "contractNumber": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "site": { "type": "string" }, "status": { "type": "string" }, "outDate": { "type": "string", "format": "date" }, "dueBack": { "type": "string" }, "offHiredOn": { "type": "string", "format": "date" }, "offHireRequestedBy": { "type": "string" }, "offHireRequestedAt": { "type": "string" }, "delivery": { "type": "boolean" }, "collection": { "type": "boolean" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiRentalContractsByIdResponseLinesItem" } }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiRentalContractsByIdResponseChargesItem" } }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiRentalContractsByIdResponseStopsItem" } }, "photoCount": { "type": "integer" }, "depositHeld": { "type": "number" }, "total": { "type": "number" }, "billing": { "type": "string" }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiRentalContractsByIdResponseInvoicesItem" } } } }, "GetApiRentalContractsByIdResponseChargesItem": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unitAmount": { "type": "number" }, "total": { "type": "number" } } }, "GetApiRentalContractsByIdResponseInvoicesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "kind": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "status": { "type": "string" }, "total": { "type": "number" }, "amountDue": { "type": "number" } } }, "GetApiRentalContractsByIdResponseLinesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "hireItemId": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "quantity": { "type": "integer" }, "qtyOut": { "type": "integer" }, "qtyBack": { "type": "integer" }, "qtyMissing": { "type": "integer" }, "withCustomer": { "type": "integer" }, "toGo": { "type": "integer" }, "offHiredOn": { "type": "string", "format": "date" }, "hireCharge": { "type": "number" }, "periods": { "type": "string" }, "meterUnit": { "type": "string" }, "meterOut": { "type": "number" }, "crossHired": { "type": "boolean" }, "supplierName": { "type": "string" } } }, "GetApiRentalContractsByIdResponseStopsItem": { "description": "Shared by 6 operations.", "type": "object", "properties": { "stopId": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "stopType": { "type": "string" }, "status": { "type": "string" }, "hasProof": { "type": "boolean" } } }, "GetApiRentalUtilisationResponseTotals": { "type": "object", "properties": { "itemClass": { "type": "string" }, "items": { "type": "integer" }, "unitDaysOwned": { "type": "integer" }, "unitDaysOnHire": { "type": "integer" }, "utilisation": { "type": "number" }, "income": { "type": "number" }, "depreciation": { "type": "number" }, "serviceCost": { "type": "number" }, "net": { "type": "number" } } }, "GetApiReportsAfsLeadSchedulesResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "statementKey": { "type": "string" }, "lineLabel": { "type": "string" }, "currentUnits": { "type": "integer" }, "priorUnits": { "type": "integer" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsAfsLeadSchedulesResponseItemAccountsItem" } }, "ties": { "type": "boolean" } } }, "GetApiReportsAfsLeadSchedulesResponseItemAccountsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "accountType": { "type": "string" }, "currentUnits": { "type": "integer" }, "priorUnits": { "type": "integer" } } }, "GetApiReportsAfsResponseCashFlows": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsAfsResponseCashFlowsLinesItem" } } } }, "GetApiReportsAfsResponseCashFlowsLinesItem": { "type": "object", "properties": { "label": { "type": "string" }, "currentUnits": { "type": "integer" }, "priorUnits": { "type": "integer" }, "noteRef": { "type": "integer" }, "kind": { "type": "string" }, "indent": { "type": "integer" }, "accountCodes": { "type": "array", "items": { "type": "string" } } } }, "GetApiReportsAfsSettingsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "financialYearEnd": { "type": "string", "format": "date" }, "consolidated": { "type": "boolean" }, "status": { "type": "string" }, "rounding": { "type": "string" }, "preparedBy": { "type": "string" }, "preparedByCapacity": { "type": "string" }, "approvedOn": { "type": "string", "format": "date" }, "governingBodyMembers": { "type": "array", "items": { "type": "string" } }, "practitionerName": { "type": "string" }, "practitionerFirm": { "type": "string" }, "assuranceEngagement": { "type": "string" }, "natureOfBusiness": { "type": "string" }, "goingConcernNote": { "type": "string" }, "subsequentEventsNote": { "type": "string" }, "ownersLoanTerms": { "type": "string" }, "provisionsNote": { "type": "string" }, "contingenciesNote": { "type": "string" }, "noContingentLiabilities": { "type": "boolean" }, "averageEmployees": { "type": "integer" }, "beneficialInterestHolders": { "type": "integer" }, "internallyCompiled": { "type": "boolean" }, "ownerManaged": { "type": "boolean" }, "publicCompany": { "type": "boolean" }, "fiduciaryAssetsOverThreshold": { "type": "boolean" }, "priorPeriodErrors": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiReportsAfsSettingsRequestPriorPeriodErrorsItem" } }, "locked": { "type": "boolean" }, "approvedAt": { "type": "string" }, "approvedBy": { "type": "string" }, "figuresHash": { "type": "string" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsAfsSettingsResponseHistoryItem" } } } }, "GetApiReportsAfsSettingsResponseHistoryItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "approvedOn": { "type": "string", "format": "date" }, "approvedAt": { "type": "string" }, "approvedBy": { "type": "string" }, "figuresHash": { "type": "string" }, "reopenedAt": { "type": "string" }, "reopenedBy": { "type": "string" }, "reopenReason": { "type": "string" } } }, "GetApiReportsAgedDebtorsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "asOfLabel": { "type": "string" }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsAgedDebtorsResponseBucketsItem" } }, "total": { "type": "number" }, "ledgerControlBalance": { "type": "number" }, "controlDifference": { "type": "number" } } }, "GetApiReportsAgedDebtorsResponseBucketsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": "number" }, "colorHex": { "type": "string" } } }, "GetApiReportsAuditTrailResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsAuditTrailResponseItemsItem" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "GetApiReportsAuditTrailResponseItemsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "actorUserId": { "type": "string" }, "actorEmail": { "type": "string" }, "actorName": { "type": "string" }, "action": { "type": "string" }, "resourceType": { "type": "string" }, "resourceId": { "type": "string" }, "severity": { "type": "string" }, "payload": { "type": "string" }, "ipAddress": { "type": "string" }, "userAgent": { "type": "string" }, "createdAt": { "type": "string" } } }, "GetApiReportsBbbeeResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "level": { "type": "integer" }, "totalScored": { "type": "integer" }, "totalMax": { "type": "integer" }, "recognitionPct": { "type": "integer" }, "elements": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsBbbeeResponseElementsItem" } } } }, "GetApiReportsBbbeeResponseElementsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "element": { "type": "string" }, "maxPoints": { "type": "integer" }, "scored": { "type": "integer" }, "pct": { "type": "integer" } } }, "GetApiReportsBreakEvenResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "periodLabel": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "revenue": { "type": "number" }, "variableCosts": { "type": "number" }, "fixedCosts": { "type": "number" }, "contributionMargin": { "type": "number" }, "contributionMarginRatio": { "type": "number" }, "breakEvenRevenue": { "type": "number" }, "marginOfSafety": { "type": "number" }, "marginOfSafetyRatio": { "type": "number" }, "operatingProfit": { "type": "number" }, "costOfSales": { "type": "number" }, "operatingExpenses": { "type": "number" }, "tiesToIncomeStatement": { "type": "boolean" }, "notComputable": { "type": "string" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsBreakEvenResponseAccountsItem" } } } }, "GetApiReportsBreakEvenResponseAccountsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "accountId": { "type": "string" }, "name": { "type": "string" }, "section": { "type": "string" }, "amount": { "type": "number" }, "behaviour": { "type": "string" }, "stated": { "type": "boolean" } } }, "GetApiReportsCashFlowResponseFinancingItem": { "description": "Shared by 6 operations.", "type": "object", "properties": { "name": { "type": "string" }, "amount": { "type": "number" } } }, "GetApiReportsDrillDownByAccountIdResponseLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "journalId": { "type": "string" }, "journalNumber": { "type": "string" }, "date": { "type": "string", "format": "date" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "reference": { "type": "string" }, "description": { "type": "string" }, "contactName": { "type": "string" }, "costCentreCode": { "type": "string" }, "debit": { "type": "number" }, "credit": { "type": "number" }, "balance": { "type": "number" } } }, "GetApiReportsFundsResponseFundsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "fundId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "restricted": { "type": "boolean" }, "opening": { "type": "number" }, "income": { "type": "number" }, "expenditure": { "type": "number" }, "surplus": { "type": "number" }, "closing": { "type": "number" } } }, "GetApiReportsIncomeStatementResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "periodLabel": { "type": "string" }, "revenue": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "costOfSales": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "operatingExpenses": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "otherIncome": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "tax": { "type": "number" } } }, "GetApiReportsSummaryResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "ytdRevenue": { "type": "number" }, "netProfit": { "type": "number" }, "totalAssets": { "type": "number" }, "outstanding": { "type": "number" }, "bbbeeScored": { "type": "integer" }, "bbbeeMax": { "type": "integer" }, "bbbeeLevel": { "type": "integer" }, "grossMarginPct": { "type": "integer" }, "netMarginPct": { "type": "integer" }, "periodLabel": { "type": "string" }, "monthlyTrend": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsSummaryResponseMonthlyTrendItem" } }, "cash": { "$ref": "#/components/schemas/GetApiReportsSummaryResponseCash" } } }, "GetApiReportsSummaryResponseCash": { "description": "Shared by 2 operations.", "type": "object", "properties": { "asOfLabel": { "type": "string" }, "ledgerBalance": { "type": "number" }, "cashAtBank": { "type": "number" }, "overdrafts": { "type": "number" }, "statementBalance": { "type": "number" }, "unreconciledDifference": { "type": "number" } } }, "GetApiReportsSummaryResponseMonthlyTrendItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "month": { "type": "string" }, "revenue": { "type": "number" }, "expenses": { "type": "number" }, "cogs": { "type": "number" }, "outputVat": { "type": "number" } } }, "GetApiSandboxResponseSandbox": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "string" } } }, "GetApiSarsDocumentsIrp6Response": { "description": "Shared by 5 operations.", "type": "object", "properties": { "taxType": { "type": "string" }, "title": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "periodLabel": { "type": "string" }, "entityName": { "type": "string" }, "taxReferenceNumber": { "type": "string" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsDocumentsIrp6ResponseSectionsItem" } }, "issues": { "type": "array", "items": { "type": "object" } }, "blockingIssues": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "object" } }, "unmappedFields": { "type": "array", "items": { "type": "string" } }, "unverifiedFieldCodes": { "type": "array", "items": { "type": "string" } }, "derivedPaymentReference": { "type": "string" }, "netAmount": { "type": "number" }, "isRefund": { "type": "boolean" }, "availableFormats": { "type": "array", "items": { "type": "string" } }, "manualSubmissionOnly": { "type": "boolean" } } }, "GetApiSarsDocumentsIrp6ResponseSectionsItem": { "description": "Shared by 8 operations.", "type": "object", "properties": { "title": { "type": "string" }, "note": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsDocumentsIrp6ResponseSectionsItemFieldsItem" } } } }, "GetApiSarsDocumentsIrp6ResponseSectionsItemFieldsItem": { "description": "Shared by 8 operations.", "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "amount": { "type": "number" }, "display": { "type": "string" }, "unmapped": { "type": "boolean" }, "confidence": { "type": "string" }, "note": { "type": "string" } } }, "GetApiSarsDocumentsIt3dResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "taxType": { "type": "string" }, "title": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "periodLabel": { "type": "string" }, "entityName": { "type": "string" }, "taxReferenceNumber": { "type": "string" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsDocumentsIrp6ResponseSectionsItem" } }, "issues": { "type": "array", "items": { "type": "object" } }, "blockingIssues": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "object" } }, "unmappedFields": { "type": "array", "items": { "type": "string" } }, "unverifiedFieldCodes": { "type": "array", "items": { "type": "string" } }, "derivedPaymentReference": { "type": "string" }, "netAmount": { "type": "number" }, "isRefund": { "type": "boolean" }, "availableFormats": { "type": "string" }, "manualSubmissionOnly": { "type": "boolean" } } }, "GetApiSarsIt14CurrentTaxResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "yearEnd": { "type": "string", "format": "date" }, "normalTax": { "type": "number" }, "paidToSars": { "type": "number" }, "charged": { "type": "number" }, "movement": { "type": "number" }, "payable": { "type": "number" } } }, "GetApiSarsIt14ResponseReconciliationItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": "number" }, "subtotal": { "type": "boolean" } } }, "GetApiSarsPrepaidExpensesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "asOf": { "type": "string", "format": "date" }, "expenses": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsPrepaidExpensesResponseExpensesItem" } }, "unexpired": { "type": "number" }, "deductedWhenPaid": { "type": "number" }, "accountBalance": { "type": "number" }, "unclassified": { "type": "number" } } }, "GetApiSarsPrepaidExpensesResponseExpensesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "paidOn": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "serviceStart": { "type": "string", "format": "date" }, "serviceEnd": { "type": "string", "format": "date" }, "exempt": { "type": "boolean" }, "exemptReason": { "type": "string" }, "unexpired": { "type": "number" }, "expenseAccountCode": { "type": "string" }, "released": { "type": "number" } } }, "GetApiSarsSbcResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "yearEnd": { "type": "string", "format": "date" }, "shareholdersAllNaturalPersons": { "type": "boolean" }, "grossIncomeWithinLimit": { "type": "boolean" }, "noSharesInOtherCompanies": { "type": "boolean" }, "investmentAndServiceIncomeWithinLimit": { "type": "boolean" }, "notPersonalServiceProvider": { "type": "boolean" }, "qualifies": { "type": "boolean" }, "confirmedAt": { "type": "string" }, "grossIncomeOnLedger": { "type": "number" } } }, "GetApiSarsSection24cClaimsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "yearEnd": { "type": "string", "format": "date" }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsSection24cClaimsResponseClaimsItem" } }, "claimed": { "type": "number" }, "incomeReceivedInAdvance": { "type": "number" }, "allowed": { "type": "number" } } }, "GetApiSarsSection24cClaimsResponseClaimsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "yearEnd": { "type": "string", "format": "date" }, "contractRef": { "type": "string" }, "contractDate": { "type": "string", "format": "date" }, "incomeReceivedInAdvance": { "type": "number" }, "futureExpenditure": { "type": "number" }, "allowance": { "type": "number" } } }, "GetApiSarsTurnoverTaxResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "taxYearEndYear": { "type": "integer" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "registered": { "type": "boolean" }, "turnoverToDate": { "type": "number" }, "completedMonths": { "type": "integer" }, "projectedTurnover": { "type": "number" }, "taxOnTurnoverToDate": { "type": "number" }, "estimatedTax": { "type": "number" }, "firstInterim": { "$ref": "#/components/schemas/GetApiSarsTurnoverTaxResponseFirstInterim" }, "secondInterim": { "$ref": "#/components/schemas/GetApiSarsTurnoverTaxResponseFirstInterim" }, "annualReturnOpens": { "type": "string", "format": "date" }, "annualReturnDue": { "type": "string", "format": "date" }, "turnoverLimit": { "type": "number" }, "issues": { "type": "array", "items": { "type": "object" } } } }, "GetApiSarsTurnoverTaxResponseFirstInterim": { "description": "Shared by 2 operations.", "type": "object", "properties": { "amount": { "type": "number" }, "dueDate": { "type": "string", "format": "date" } } }, "GetApiSarsVatBasisResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "current": { "type": "string" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiSarsVatBasisRequest" } }, "paymentsRefusal": { "type": "null" } } }, "GetApiSarsVatCreditorsResponseUnpaidItem": { "type": "object", "properties": { "billId": { "type": "string" }, "supplier": { "type": "string" }, "reference": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "twelveMonthsEnd": { "type": "string", "format": "date" }, "adjustmentDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "vatAmount": { "type": "number" }, "groupCompany": { "type": "boolean" } } }, "GetApiSarsVatDeregistrationResponseAssetsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "costIncludingVat": { "type": "number" }, "openMarketValue": { "type": "number" }, "value": { "type": "number" }, "vatAmount": { "type": "number" } } }, "GetApiSarsVatDeregistrationResponseCreditorsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "billId": { "type": "string" }, "reference": { "type": "string" }, "amount": { "type": "number" }, "vatAmount": { "type": "number" } } }, "GetApiSarsVatDeregistrationResponseStockItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "costIncludingVat": { "type": "number" }, "openMarketValue": { "type": "null" }, "value": { "type": "number" }, "vatAmount": { "type": "number" } } }, "GetApiSarsVatReviewResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "findings": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsVatReviewResponseFindingsItem" } } } }, "GetApiSarsVatReviewResponseFindingsItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "filed": { "type": "boolean" }, "reference": { "type": "string" }, "message": { "type": "string" }, "vatEffect": { "type": "number" }, "check": { "type": "boolean" }, "route": { "type": "string" }, "press": { "type": "string" }, "documentId": { "type": "string" }, "decision": { "type": "null" }, "decisionReason": { "type": "null" } } }, "GetApiStandardCostsByProductIdResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "bomId": { "type": "string" }, "bomName": { "type": "string" }, "materialCost": { "type": "number" }, "labourCost": { "type": "number" }, "overheadCost": { "type": "number" }, "totalCost": { "type": "number" }, "labourHoursPerUnit": { "type": "number" }, "labourRate": { "type": "number" }, "costSource": { "type": "string" }, "bomLevel": { "type": "integer" }, "version": { "type": "integer" }, "effectiveFrom": { "type": "string", "format": "date" }, "notes": { "type": "string" } } }, "GetApiSuppliersAgedResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "email": { "type": "string" }, "asOf": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSuppliersAgedResponseItemLinesItem" } }, "totalOutstanding": { "type": "number" }, "current": { "type": "number" }, "days30": { "type": "number" }, "days60": { "type": "number" }, "days90Plus": { "type": "number" }, "oldestDays": { "type": "integer" } } }, "GetApiSuppliersAgedResponseItemLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "billId": { "type": "string" }, "reference": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "total": { "type": "number" }, "outstanding": { "type": "number" }, "daysOverdue": { "type": "integer" }, "category": { "type": "string" } } }, "GetApiSuppliersByIdBankDetailsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "contactId": { "type": "string" }, "supplierName": { "type": "string" }, "bankName": { "type": "string" }, "accountNumber": { "type": "string" }, "branchCode": { "type": "string" }, "accountType": { "type": "string" }, "updatedAt": { "type": "string" }, "updatedByName": { "type": "string" }, "blocker": { "type": "string" } } }, "GetApiTenantEntitlementsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "plan": { "type": "string" }, "planDisplayName": { "type": "string" }, "maxUsers": { "type": "integer" }, "licenseValidUntil": { "type": "string", "format": "date" }, "modules": { "type": "array", "items": { "type": "string" } }, "expired": { "type": "boolean" }, "activeUsers": { "type": "integer" }, "invoicesThisMonth": { "type": "integer" }, "invoiceLimit": { "type": "integer" }, "payrollEmployees": { "type": "integer" }, "payrollBand": { "type": "string" }, "payrollBandLicensed": { "type": "string" }, "payrollBandMonthly": { "type": "number" }, "payrollBandExceeded": { "type": "boolean" }, "payrollBandHeadroom": { "type": "integer" }, "payrollBandSummary": { "type": "string" }, "storageUsedBytes": { "type": "integer" }, "storageUsedGb": { "type": "integer" }, "storageIncludedGb": { "type": "integer" }, "storageExtraGb": { "type": "integer" }, "storageMonthlyUplift": { "type": "number" }, "storageExceedsLicensed": { "type": "boolean" }, "storageHeadroomGb": { "type": "integer" }, "storageSummary": { "type": "string" }, "whatsAppUsed": { "type": "integer" }, "whatsAppIncluded": { "type": "integer" }, "whatsAppExtra": { "type": "integer" }, "whatsAppMonthlyUplift": { "type": "number" }, "whatsAppHeadroom": { "type": "integer" }, "whatsAppSummary": { "type": "string" }, "scanUsed": { "type": "integer" }, "scanIncluded": { "type": "integer" }, "scanExtra": { "type": "integer" }, "scanMonthlyUplift": { "type": "number" }, "scanHeadroom": { "type": "integer" }, "aiAssist": { "type": "boolean" }, "scanSummary": { "type": "string" }, "practiceClients": { "type": "integer" }, "practicePaidClients": { "type": "integer" }, "practiceStatus": { "type": "string" }, "practiceStatusName": { "type": "string" }, "practicePayoutPercent": { "type": "number" }, "practiceMonthlyPayout": { "type": "number" }, "practiceClientsToNextStatus": { "type": "integer" }, "practiceSummary": { "type": "string" }, "planIncludedUsers": { "type": "integer" }, "companies": { "type": "integer" }, "maxCompanies": { "type": "integer" }, "planIncludedCompanies": { "type": "integer" }, "companiesSummary": { "type": "string" }, "addons": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiTenantEntitlementsResponseAddonsItem" } }, "availableAddons": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiTenantEntitlementsResponseAddonsItem" } }, "addonsMonthlyTotal": { "type": "number" }, "addonUpgradeSuggestion": { "type": "string" }, "apiKeysUsed": { "type": "integer" }, "apiKeysIncluded": { "type": "integer" }, "apiKeysHeadroom": { "type": "integer" }, "apiKeysSummary": { "type": "string" } } }, "GetApiTenantEntitlementsResponseAddonsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "blurb": { "type": "string" }, "unitPriceMonthly": { "type": "number" }, "quantity": { "type": "integer" }, "monthlyPrice": { "type": "number" }, "seatsPerUnit": { "type": "integer" }, "unlocks": { "type": "array", "items": { "type": "string" } }, "maxQuantity": { "type": "integer" }, "unitLabel": { "type": "string" } } }, "GetApiTenantSettingsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "taxVat": { "$ref": "#/components/schemas/GetApiTenantSettingsResponseTaxVat" }, "branding": { "$ref": "#/components/schemas/PutApiTenantSettingsRequestBranding" }, "localisation": { "$ref": "#/components/schemas/PutApiTenantSettingsRequestLocalisation" }, "integrations": { "$ref": "#/components/schemas/GetApiTenantSettingsResponseIntegrations" }, "notifications": { "$ref": "#/components/schemas/GetApiTenantSettingsResponseIntegrations" }, "dataPrefs": { "$ref": "#/components/schemas/PutApiTenantSettingsRequestDataPrefs" } } }, "GetApiTenantSettingsResponseIntegrations": { "description": "Shared by 2 operations.", "type": "object", "properties": { "key": { "type": "boolean" } } }, "GetApiTenantSettingsResponseTaxVat": { "description": "Shared by 2 operations.", "type": "object", "properties": { "isVatRegistered": { "type": "boolean" }, "vatRegistrationDate": { "type": "string", "format": "date" }, "vatPeriod": { "type": "string" }, "standardVatRate": { "type": "number" }, "drcEnabled": { "type": "boolean" }, "provisionalTaxPayer": { "type": "boolean" }, "sarsIsvConnected": { "type": "boolean" }, "sarsTaxRefNumber": { "type": "string" }, "incomeTaxRate": { "type": "number" } } }, "GetApiTimeTrackingPeopleResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "defaultChargeRate": { "type": "number" }, "defaultCostRate": { "type": "number" }, "weeklyHours": { "type": "number" } } }, "GetApiTimeTrackingProjectsByIdMilestonesResponseItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "amount": { "type": "number" }, "dueDate": { "type": "string", "format": "date" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" } } }, "GetApiUsersResponseItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "role": { "type": "string" }, "roleId": { "type": "string" }, "isActive": { "type": "boolean" }, "lastLoginAt": { "type": "string" }, "twoFactorEnabled": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "GetApiWebhookEventsResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "ts": { "type": "string" }, "gateway": { "type": "string" }, "ref": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "matched": { "type": "string" }, "status": { "type": "string" }, "note": { "type": "string" } } }, "GetApiWebhooksByIdDeliveriesResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "lastStatusCode": { "type": "integer" }, "lastError": { "type": "string" }, "nextAttemptAt": { "type": "string" }, "deliveredAt": { "type": "string" }, "createdAt": { "type": "string" } } }, "GetApiWebhooksResponseItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "secretHint": { "type": "string" }, "apiKeyId": { "type": "string" }, "lastDeliveryStatus": { "type": "string" }, "lastDeliveryAt": { "type": "string" }, "lastStatusCode": { "type": "integer" }, "lastError": { "type": "string" }, "pendingCount": { "type": "integer" }, "createdAt": { "type": "string" } } }, "GetApiWorkOrdersByIdChildrenResponseChildrenItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "woNumber": { "type": "string" }, "productName": { "type": "string" }, "qty": { "type": "number" }, "status": { "type": "string" }, "plannedFinish": { "type": "string", "format": "date" } } }, "GetApiWorkOrdersByIdCostingResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "workOrderId": { "type": "string" }, "woNumber": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "status": { "type": "string" }, "qtyPlanned": { "type": "number" }, "qtyCompleted": { "type": "number" }, "qtyScrapped": { "type": "number" }, "stdMaterialPerUnit": { "type": "number" }, "stdLabourPerUnit": { "type": "number" }, "stdOverheadPerUnit": { "type": "number" }, "stdTotalPerUnit": { "type": "number" }, "stdHoursPerUnit": { "type": "number" }, "stdLabourRate": { "type": "number" }, "standardCostOfOutput": { "type": "number" }, "actualMaterial": { "type": "number" }, "actualLabour": { "type": "number" }, "actualOverhead": { "type": "number" }, "actualTotal": { "type": "number" }, "actualHours": { "type": "number" }, "wipRelieved": { "type": "number" }, "wipVarianceCleared": { "type": "number" }, "wipBalance": { "type": "number" }, "totalVariance": { "type": "number" }, "variances": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdCostingResponseVariancesItem" } }, "issues": { "type": "array", "items": { "type": "object" } }, "labour": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdCostingResponseLabourItem" } }, "hasRouting": { "type": "boolean" }, "standardPinned": { "type": "boolean" }, "completions": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdCostingResponseCompletionsItem" } } } }, "GetApiWorkOrdersByIdCostingResponseCompletionsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "qtyCompleted": { "type": "number" }, "qtyScrapped": { "type": "number" }, "standardUnitCost": { "type": "number" }, "standardTotal": { "type": "number" }, "isFinal": { "type": "boolean" }, "completedAt": { "type": "string" }, "completedByName": { "type": "string" }, "reference": { "type": "string" }, "reversedAt": { "type": "string" }, "reversalOfId": { "type": "string" }, "reversalReason": { "type": "string" }, "qtyStillInStock": { "type": "number" }, "canReverse": { "type": "boolean" } } }, "GetApiWorkOrdersByIdCostingResponseLabourItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "hours": { "type": "number" }, "actualRate": { "type": "number" }, "actualCost": { "type": "number" }, "standardRate": { "type": "number" }, "overheadCost": { "type": "number" }, "entryType": { "type": "string" }, "entryDate": { "type": "string", "format": "date" }, "employeeName": { "type": "string" }, "notes": { "type": "string" }, "journalId": { "type": "string" } } }, "GetApiWorkOrdersByIdCostingResponseVariancesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "accountCode": { "type": "string" }, "productId": { "type": "string" }, "standardQty": { "type": "number" }, "actualQty": { "type": "number" }, "standardRate": { "type": "number" }, "actualRate": { "type": "number" }, "explanation": { "type": "string" }, "favourable": { "type": "boolean" }, "journalId": { "type": "string" } } }, "GetApiWorkOrdersByIdNonConformancesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "boards": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdNonConformancesResponseItemsItem" } }, "mayRaise": { "type": "boolean" } } }, "GetApiWorkOrdersByIdNonConformancesResponseItemsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "itemKey": { "type": "string" }, "title": { "type": "string" }, "boardName": { "type": "string" }, "stage": { "type": "string" }, "closed": { "type": "boolean" }, "createdAt": { "type": "string" }, "lotNumber": { "type": "string" } } }, "GetApiWorkOrdersByIdOperationsResponse": { "description": "Shared by 11 operations.", "type": "object", "properties": { "workOrderId": { "type": "string" }, "woNumber": { "type": "string" }, "status": { "type": "string" }, "productName": { "type": "string" }, "routingId": { "type": "string" }, "routingName": { "type": "string" }, "expectedYieldPercent": { "type": "number" }, "qtyPlanned": { "type": "number" }, "qtyToStart": { "type": "number" }, "qtyCompleted": { "type": "number" }, "qtyScrapped": { "type": "number" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponseOperationsItem" } }, "operationCount": { "type": "integer" }, "completedOperationCount": { "type": "integer" }, "percentComplete": { "type": "number" }, "plannedHours": { "type": "number" }, "actualHours": { "type": "number" }, "varianceHours": { "type": "number" }, "actualLabourCost": { "type": "number" }, "currentOperation": { "type": "string" } } }, "GetApiWorkOrdersByIdOperationsResponseOperationsItem": { "description": "Shared by 13 operations.", "type": "object", "properties": { "id": { "type": "string" }, "workOrderId": { "type": "string" }, "woNumber": { "type": "string" }, "routingOperationId": { "type": "string" }, "sequenceNo": { "type": "integer" }, "description": { "type": "string" }, "workCentreId": { "type": "string" }, "workCentreCode": { "type": "string" }, "workCentreName": { "type": "string" }, "status": { "type": "string" }, "plannedSetupHours": { "type": "number" }, "plannedRunHours": { "type": "number" }, "plannedHours": { "type": "number" }, "actualHours": { "type": "number" }, "varianceHours": { "type": "number" }, "qtyCompleted": { "type": "number" }, "qtyScrapped": { "type": "number" }, "labourRatePerHour": { "type": "number" }, "overheadRatePerHour": { "type": "number" }, "actualCost": { "type": "number" }, "plannedCost": { "type": "number" }, "isSubcontract": { "type": "boolean" }, "subcontractSupplierId": { "type": "string" }, "subcontractSupplierName": { "type": "string" }, "scheduledStart": { "type": "string", "format": "date" }, "scheduledFinish": { "type": "string" }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" }, "operatorName": { "type": "string" }, "notes": { "type": "string" } } }, "GetApiWorkOrdersByIdResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "woNumber": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "bomId": { "type": "string" }, "bomName": { "type": "string" }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "qtyPlanned": { "type": "number" }, "qtyCompleted": { "type": "number" }, "status": { "type": "string" }, "priority": { "type": "integer" }, "plannedStart": { "type": "string", "format": "date" }, "plannedFinish": { "type": "string" }, "actualStart": { "type": "string", "format": "date" }, "actualFinish": { "type": "string" }, "estimatedCost": { "type": "number" }, "actualCost": { "type": "number" }, "assemblyBuildId": { "type": "string" }, "mrpRunNumber": { "type": "string" }, "notes": { "type": "string" }, "shortages": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdResponseShortagesItem" } }, "canStart": { "type": "boolean" } } }, "GetApiWorkOrdersByIdResponseShortagesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "required": { "type": "number" }, "onHand": { "type": "number" }, "short": { "type": "number" } } }, "GetApiWorkOrdersByIdSubcontractOrdersResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdSubcontractOrdersResponseOrdersItem" } }, "note": { "type": "string" } } }, "GetApiWorkOrdersByIdSubcontractOrdersResponseOrdersItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "status": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "workOrderId": { "type": "string" }, "operationId": { "type": "string" }, "step": { "type": "string" }, "qtyOrdered": { "type": "number" }, "qtyReceived": { "type": "number" }, "unitCost": { "type": "number" }, "billId": { "type": "string" }, "source": { "type": "string" } } }, "GetApiWorkOrdersOperationsByOpIdChecksResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersOperationsByOpIdChecksResponseItemsItem" } } } }, "GetApiWorkOrdersOperationsByOpIdChecksResponseItemsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "operationId": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "minValue": { "type": "number" }, "maxValue": { "type": "number" }, "unit": { "type": "string" }, "result": { "type": "string" }, "measuredValue": { "type": "number" }, "notes": { "type": "null" }, "recordedByName": { "type": "string" }, "recordedAt": { "type": "string" } } }, "GetApiWorkOrdersOperationsByOpIdFreeIssueResponseItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "location": { "type": "string" }, "sent": { "type": "number" }, "consumed": { "type": "number" }, "returned": { "type": "number" }, "atSubcontractor": { "type": "number" }, "perUnit": { "type": "number" } } }, "GetApiWorkflowsBoardsByIdInsightsResponseColumnsItem": { "type": "object", "properties": { "columnId": { "type": "string" }, "name": { "type": "string" }, "stage": { "type": "string" }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "over": { "type": "boolean" } } }, "GetApiWorkflowsItemsByIdResponseAttachmentsItem": { "description": "Shared by 11 operations.", "type": "object", "properties": { "id": { "type": "string" }, "attachmentId": { "type": "string" }, "filename": { "type": "string" }, "caption": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "url": { "type": "string" }, "uploadedByName": { "type": "string" }, "createdAt": { "type": "string" } } }, "GetDriverApiV1TripsByIdMessagesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "driverName": { "type": "string" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/PostDriverApiV1TripsByIdMessagesResponse" } }, "unread": { "type": "integer" } } }, "GetDriverApiV1TripsByIdResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tripNumber": { "type": "string" }, "tripDate": { "type": "string", "format": "date" }, "status": { "type": "string" }, "routeName": { "type": "string" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "plannedDeparture": { "type": "string" }, "startOdometerKm": { "type": "number" }, "notes": { "type": "string" }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/GetDriverApiV1TripsByIdResponseStopsItem" } }, "stopsTotal": { "type": "integer" }, "stopsRemaining": { "type": "integer" }, "preTripChecklist": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsInspectionChecklistResponseItemsItem" } }, "preTripState": { "type": "string" }, "preTripBlocker": { "type": "string" } } }, "GetDriverApiV1TripsByIdResponseStopsItem": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "stopType": { "type": "string" }, "status": { "type": "string" }, "customerName": { "type": "string" }, "documentNumber": { "type": "string" }, "address": { "type": "string" }, "suburb": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "contactName": { "type": "string" }, "contactPhone": { "type": "string" }, "instructions": { "type": "string" }, "windowFrom": { "type": "string", "format": "date" }, "windowTo": { "type": "string", "format": "date" }, "arrivedAt": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetDriverApiV1TripsByIdResponseStopsItemLinesItem" } }, "hasProof": { "type": "boolean" }, "collectable": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponseCollectable" }, "collection": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponseCollection" } } }, "GetDriverApiV1TripsByIdResponseStopsItemLinesItem": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "qtyOrdered": { "type": "number" }, "qtyDelivered": { "type": "number" }, "uom": { "type": "string" }, "batchNumber": { "type": "string" }, "productBarcode": { "type": "string" }, "qtyLoaded": { "type": "number" }, "service": { "type": "boolean" } } }, "GetSupplierApiV1ComplianceResponseMissingItem": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "kindLabel": { "type": "string" }, "consequence": { "type": "string" }, "reference": { "type": "string" }, "issuedOn": { "type": "string", "format": "date" }, "expiresOn": { "type": "string", "format": "date" }, "state": { "type": "string" }, "stateLabel": { "type": "string" }, "daysUntilExpiry": { "type": "integer" }, "claimedBbbeeLevel": { "type": "integer" }, "reviewNote": { "type": "string" }, "fileUrl": { "type": "string" }, "submittedAt": { "type": "string" } } }, "GetSupplierApiV1DespatchesResponseItemLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "poLineId": { "type": "string" }, "description": { "type": "string" }, "qty": { "type": "number" } } }, "GetSupplierApiV1InvoicesResponseItem": { "description": "Shared by 13 operations.", "type": "object", "properties": { "id": { "type": "string" }, "invoiceNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "submittedAt": { "type": "string" }, "orderNumber": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostSupplierApiV1InvoicesRequestLinesItem" } }, "canWithdraw": { "type": "boolean" }, "matchStatus": { "type": "string" }, "matchNote": { "type": "string" } } }, "GetSupplierApiV1OffersResponseItemLinesItem": { "description": "Shared by 13 operations.", "type": "object", "properties": { "rfqLineId": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "notes": { "type": "string" }, "lineTotal": { "type": "number" } } }, "GetSupplierApiV1OrdersByIdResponse": { "description": "Shared by 12 operations.", "type": "object", "properties": { "id": { "type": "string" }, "orderNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "expectedDate": { "type": "string", "format": "date" }, "status": { "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "number" }, "vatTotal": { "type": "number" }, "total": { "type": "number" }, "deliveryAddress": { "type": "string" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1OrdersByIdResponseLinesItem" } }, "acknowledgedAt": { "type": "string" }, "acknowledgedBy": { "type": "string" }, "ackStatus": { "type": "string" }, "promisedDate": { "type": "string", "format": "date" }, "ackNote": { "type": "string" }, "canAcknowledge": { "type": "boolean" }, "canInvoice": { "type": "boolean" }, "submittedInvoices": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1InvoicesResponseItem" } } } }, "GetSupplierApiV1OrdersByIdResponseLinesItem": { "description": "Shared by 12 operations.", "type": "object", "properties": { "id": { "type": "string" }, "lineNumber": { "type": "integer" }, "description": { "type": "string" }, "productCode": { "type": "string" }, "quantity": { "type": "number" }, "qtyReceived": { "type": "number" }, "unitPrice": { "type": "number" }, "vatRate": { "type": "number" }, "lineTotal": { "type": "number" } } }, "GetSupplierApiV1RegistrationResponseOptionalDocumentsItem": { "type": "object", "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "expires": { "type": "boolean" }, "consequence": { "type": "string" } } }, "GetSupplierApiV1RfqsByIdResponse": { "description": "Shared by 12 operations.", "type": "object", "properties": { "id": { "type": "string" }, "rfqNumber": { "type": "string" }, "title": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "responseDueDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "deliveryAddress": { "type": "string" }, "terms": { "type": "string" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1RfqsByIdResponseLinesItem" } }, "invitationStatus": { "type": "string" }, "canQuote": { "type": "boolean" }, "submittedQuote": { "$ref": "#/components/schemas/GetSupplierApiV1RfqsByIdResponseSubmittedQuote" } } }, "GetSupplierApiV1RfqsByIdResponseLinesItem": { "description": "Shared by 12 operations.", "type": "object", "properties": { "id": { "type": "string" }, "lineNumber": { "type": "integer" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "requiredDate": { "type": "string", "format": "date" } } }, "GetSupplierApiV1RfqsByIdResponseSubmittedQuote": { "description": "Shared by 12 operations.", "type": "object", "properties": { "id": { "type": "string" }, "quoteNumber": { "type": "string" }, "quoteDate": { "type": "string", "format": "date" }, "validUntil": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "subtotal": { "type": "number" }, "vatAmount": { "type": "number" }, "total": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "paymentTermsDays": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1OffersResponseItemLinesItem" } } } }, "PatchApiContactsByIdRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "editId": { "type": "string" }, "base": { "$ref": "#/components/schemas/PatchApiContactsByIdRequestBase" }, "changes": { "$ref": "#/components/schemas/PatchApiContactsByIdRequestBase" }, "baseUpdatedAt": { "type": "string" }, "conflicts": { "type": "array", "items": { "type": "object" } } } }, "PatchApiContactsByIdRequestBase": { "description": "Shared by 3 operations.", "type": "object", "properties": { "email": { "type": "string" } } }, "PatchApiPractitionerLinksByIdRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "accessLevel": { "type": "string" } } }, "PostApiAccountsResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "parentId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "accountType": { "type": "string" }, "accountSubtype": { "type": "string" }, "currency": { "type": "string" }, "isActive": { "type": "boolean" }, "isSystem": { "type": "boolean" }, "normalBalance": { "type": "string" }, "children": { "type": "array", "items": { "type": "null" } } } }, "PostApiAlertRulesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "amount": { "type": "number" }, "days": { "type": "integer" }, "description": { "type": "string" }, "createdAt": { "type": "string" } } }, "PostApiBankAccountsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" }, "currency": { "type": "string" }, "currentBalance": { "type": "number" }, "statementBalance": { "type": "number" }, "type": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiBankFeedsResponseAccountsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "investecAccountId": { "type": "string" }, "name": { "type": "string" }, "masked": { "type": "string" }, "currency": { "type": "string" }, "linkedBankAccountId": { "type": "string" }, "suggestedBankAccountId": { "type": "string" } } }, "PostApiBankImportsByBatchIdUndoResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "removed": { "type": "integer" }, "kept": { "type": "integer" }, "sentence": { "type": "string" }, "keptLines": { "type": "array", "items": { "type": "object" } } } }, "PostApiBankRulesApplyResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "matched": { "type": "integer" }, "categorised": { "type": "integer" }, "created": { "type": "integer" }, "skipped": { "type": "integer" }, "dryRun": { "type": "boolean" }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBankRulesApplyResponseOutcomesItem" } } } }, "PostApiBankRulesApplyResponseOutcomesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "transactionId": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "category": { "type": "string" }, "createKind": { "type": "string" }, "createdId": { "type": "string" }, "skippedReason": { "type": "string" } } }, "PostApiBankRulesRequestAction": { "description": "Shared by 2 operations.", "type": "object", "properties": { "category": { "type": "string" }, "createKind": { "type": "string" }, "accountCode": { "type": "string" } } }, "PostApiBankRulesRequestConditionsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "field": { "type": "string" }, "op": { "type": "string" }, "value": { "type": "string" } } }, "PostApiBankRulesResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "conditions": { "type": "string" }, "action": { "type": "string" }, "priority": { "type": "integer" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiBankStatementsConvertResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "format": { "type": "string" }, "detected": { "type": "string" }, "accountReference": { "type": "string" }, "currency": { "type": "string" }, "statementStart": { "type": "string", "format": "date" }, "statementEnd": { "type": "string", "format": "date" }, "openingBalance": { "type": "number" }, "closingBalance": { "type": "number" }, "bankProfile": { "$ref": "#/components/schemas/PostApiBankStatementsImportResponseBankProfile" }, "total": { "type": "integer" }, "newCount": { "type": "integer" }, "duplicateCount": { "type": "integer" }, "balances": { "type": "boolean" }, "balanceDifference": { "type": "number" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBankStatementsConvertResponseRowsItem" } }, "issues": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "object" } }, "documentText": { "type": "string" }, "pageCount": { "type": "integer" }, "pagesRead": { "type": "integer" }, "truncated": { "type": "boolean" }, "exactText": { "type": "boolean" }, "readBy": { "type": "string" } } }, "PostApiBankStatementsConvertResponseRowsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "reference": { "type": "string" }, "runningBalance": { "type": "number" } } }, "PostApiBankStatementsImportResponseBankProfile": { "description": "Shared by 3 operations.", "type": "object", "properties": { "bank": { "type": "string" }, "label": { "type": "string" }, "confidence": { "type": "number" }, "evidence": { "type": "array", "items": { "type": "string" } }, "matched": { "type": "boolean" }, "source": { "type": "string" } } }, "PostApiBankTransactionsByIdCodeResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string" }, "ledgerNotice": { "type": "string" } } }, "PostApiBankTransactionsResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "bankAccountId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "reference": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "matchedInvoiceId": { "type": "string" }, "matchedExpenseId": { "type": "string" }, "category": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "source": { "type": "string" }, "autoCreatedKind": { "type": "string" }, "autoCreatedId": { "type": "string" }, "ledgerNotice": { "type": "string" } } }, "PostApiBankTransfersResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "fromBankAccountId": { "type": "string" }, "fromBankAccountName": { "type": "string" }, "toBankAccountId": { "type": "string" }, "toBankAccountName": { "type": "string" }, "transferDate": { "type": "string", "format": "date" }, "amountOut": { "type": "number" }, "amountIn": { "type": "number" }, "currency": { "type": "string" }, "outLineId": { "type": "string" }, "inLineId": { "type": "string" }, "summary": { "type": "string" }, "ledgerNotice": { "type": "null" }, "awaitingOtherSide": { "type": "boolean" } } }, "PostApiBillsByIdPaymentsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "amountPaid": { "type": "number" }, "amountDue": { "type": "number" }, "contactId": { "type": "string" }, "companyId": { "type": "string" }, "costCentreId": { "type": "string" }, "analysis2Id": { "type": "string" }, "analysis3Id": { "type": "string" }, "vendor": { "type": "string" }, "billNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRate": { "type": "number" }, "currency": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "recurring": { "type": "boolean" }, "frequency": { "type": "string" }, "nextDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "recurrenceActive": { "type": "boolean" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "paidAt": { "type": "string" }, "jobCardId": { "type": "string" }, "jobNumber": { "type": "string" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "kind": { "type": "string" }, "creditedBillId": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBillsByIdPaymentsResponseLinesItem" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "ledgerNotice": { "type": "string" }, "paymentHold": { "type": "string" }, "exchangeRate": { "type": "number" }, "paymentFxRate": { "type": "number" }, "baseGross": { "type": "number" }, "approvalStatus": { "type": "string" }, "approvedBy": { "type": "string" }, "approvedByName": { "type": "string" }, "approvedAt": { "type": "string" }, "rejectionReason": { "type": "string" }, "approvalProgress": { "$ref": "#/components/schemas/PostApiBillsByIdRejectResponseApprovalProgress" }, "documentUrl": { "type": "string" }, "documentVatUnclaimed": { "type": "number" }, "vatNotices": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBillsByIdPaymentsResponseVatNoticesItem" } }, "inputVatNotClaimed": { "type": "number" }, "sellerDeclarationUrl": { "type": "null" }, "sellerDeclarationSignedOn": { "type": "null" } } }, "PostApiBillsByIdPaymentsResponseLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "lineNumber": { "type": "integer" }, "description": { "type": "string" }, "productId": { "type": "string" }, "poLineId": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "vatRate": { "type": "number" }, "vatInclusive": { "type": "boolean" }, "discountRate": { "type": "number" }, "discountFixed": { "type": "number" }, "lineTotal": { "type": "number" }, "vatAmount": { "type": "number" }, "category": { "type": "string" }, "accountId": { "type": "string" }, "vatType": { "type": "string" }, "costCentreId": { "type": "string" }, "customsReference": { "type": "null" }, "openMarketValue": { "type": "null" } } }, "PostApiBillsByIdPaymentsResponseVatNoticesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "redateTo": { "type": "string", "format": "date" } } }, "PostApiBillsByIdRejectRequest": { "description": "Shared by 9 operations.", "type": "object", "properties": { "reason": { "type": "string" } } }, "PostApiBillsByIdRejectResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "companyId": { "type": "string" }, "costCentreId": { "type": "string" }, "vendor": { "type": "string" }, "billNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRate": { "type": "number" }, "currency": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "recurring": { "type": "boolean" }, "frequency": { "type": "string" }, "nextDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "recurrenceActive": { "type": "boolean" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "paidAt": { "type": "string" }, "jobCardId": { "type": "string" }, "jobNumber": { "type": "string" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "kind": { "type": "string" }, "creditedBillId": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBillsByIdRejectResponseLinesItem" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "ledgerNotice": { "type": "string" }, "paymentHold": { "type": "string" }, "exchangeRate": { "type": "number" }, "paymentFxRate": { "type": "number" }, "baseGross": { "type": "number" }, "approvalStatus": { "type": "string" }, "approvedBy": { "type": "string" }, "approvedByName": { "type": "string" }, "approvedAt": { "type": "string" }, "rejectionReason": { "type": "string" }, "approvalProgress": { "$ref": "#/components/schemas/PostApiBillsByIdRejectResponseApprovalProgress" }, "sellerDeclarationUrl": { "type": "null" }, "sellerDeclarationSignedOn": { "type": "null" } } }, "PostApiBillsByIdRejectResponseApprovalProgress": { "description": "Shared by 4 operations.", "type": "object", "properties": { "given": { "type": "integer" }, "needed": { "type": "integer" }, "approverNames": { "type": "array", "items": { "type": "string" } }, "youApproved": { "type": "boolean" } } }, "PostApiBillsByIdRejectResponseLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "lineNumber": { "type": "integer" }, "description": { "type": "string" }, "productId": { "type": "string" }, "poLineId": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "vatRate": { "type": "number" }, "vatInclusive": { "type": "boolean" }, "discountRate": { "type": "number" }, "discountFixed": { "type": "number" }, "lineTotal": { "type": "number" }, "vatAmount": { "type": "number" }, "category": { "type": "string" }, "accountId": { "type": "string" }, "costCentreId": { "type": "string" }, "customsReference": { "type": "null" }, "openMarketValue": { "type": "null" } } }, "PostApiBillsPaymentRunsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "payDate": { "type": "string", "format": "date" }, "bankAccountId": { "type": "string" }, "bankAccountName": { "type": "string" }, "total": { "type": "number" }, "billCount": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBillsPaymentRunsResponseLinesItem" } }, "createdByName": { "type": "string" }, "createdAt": { "type": "string" }, "fileName": { "type": "string" } } }, "PostApiBillsPaymentRunsResponseLinesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "billId": { "type": "string" }, "vendor": { "type": "string" }, "billNumber": { "type": "string" }, "beneficiaryName": { "type": "string" }, "payee": { "type": "string" }, "amount": { "type": "number" }, "reference": { "type": "string" } } }, "PostApiBillsRequestLinesItem": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "lineNumber": { "type": "integer" }, "description": { "type": "string" }, "productId": { "type": "string" }, "poLineId": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "vatRate": { "type": "number" }, "vatInclusive": { "type": "boolean" }, "discountRate": { "type": "number" }, "discountFixed": { "type": "number" }, "lineTotal": { "type": "number" }, "vatAmount": { "type": "number" }, "category": { "type": "string" }, "customsReference": { "type": "null" }, "openMarketValue": { "type": "null" } } }, "PostApiBillsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "companyId": { "type": "string" }, "costCentreId": { "type": "string" }, "vendor": { "type": "string" }, "billNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRate": { "type": "number" }, "currency": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "recurring": { "type": "boolean" }, "frequency": { "type": "string" }, "nextDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "recurrenceActive": { "type": "boolean" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "paidAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "ledgerNotice": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBillsRequestLinesItem" } }, "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "sellerDeclarationUrl": { "type": "null" }, "sellerDeclarationSignedOn": { "type": "null" } } }, "PostApiBomByBomIdRejectRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "note": { "type": "string" } } }, "PostApiBomRequest": { "description": "Shared by 4 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "type": "string" }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBomRequestOutputsItem" } }, "kind": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "outputQty": { "type": "number" }, "labourCost": { "type": "number" }, "overheadCost": { "type": "number" }, "status": { "type": "string" }, "notes": { "type": "string" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBomRequestLinesItem" } }, "clientId": { "type": "string" } } }, "PostApiBomRequestLinesItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "componentProductId": { "type": "string" }, "componentVariantId": { "type": "string" }, "componentName": { "type": "string" }, "componentSku": { "type": "string" }, "qtyPer": { "type": "number" }, "scrapPercent": { "type": "number" }, "notes": { "type": "string" }, "sortOrder": { "type": "integer" }, "sourceOverride": { "type": "string" }, "leadTimeOffsetDays": { "type": "integer" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" }, "positionRef": { "type": "string" }, "unit": { "type": "string" }, "operationSeq": { "type": "integer" } } }, "PostApiBomRequestOutputsItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "kind": { "type": "string" }, "qtyPerRun": { "type": "number" }, "unitValue": { "type": "number" }, "sharePercent": { "type": "number" }, "sortOrder": { "type": "integer" }, "notes": { "type": "string" } } }, "PostApiBomResponse": { "description": "Shared by 8 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "variantId": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "outputQty": { "type": "number" }, "labourCost": { "type": "number" }, "overheadCost": { "type": "number" }, "status": { "type": "string" }, "notes": { "type": "string" }, "lineCount": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBomResponseLinesItem" } }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" }, "submittedAt": { "type": "string" }, "submittedByName": { "type": "string" }, "approvedAt": { "type": "string" }, "approvedByName": { "type": "string" }, "decisionNote": { "type": "string" }, "decidedAt": { "type": "string" }, "decidedByName": { "type": "string" }, "createdAt": { "type": "string" } } }, "PostApiBomResponseLinesItem": { "description": "Shared by 13 operations.", "type": "object", "properties": { "id": { "type": "string" }, "componentProductId": { "type": "string" }, "componentVariantId": { "type": "string" }, "componentName": { "type": "string" }, "componentSku": { "type": "string" }, "qtyPer": { "type": "number" }, "scrapPercent": { "type": "number" }, "notes": { "type": "string" }, "sortOrder": { "type": "integer" } } }, "PostApiCompaniesByIdUsersResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hasPostedLedger": { "type": "boolean" } } }, "PostApiCompaniesResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "parentCompanyId": { "type": "string" }, "registrationNumber": { "type": "string" }, "vatNumber": { "type": "string" }, "vatCategory": { "type": "string" }, "taxNumber": { "type": "string" }, "payeNumber": { "type": "string" }, "uifNumber": { "type": "string" }, "sdlNumber": { "type": "string" }, "tradingAs": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "companyType": { "type": "string" }, "fiscalYearEndMonth": { "type": "integer" }, "baseCurrency": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hasPostedLedger": { "type": "boolean" } } }, "PostApiConsolidationGroupsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "rootCompanyId": { "type": "string" }, "baseCurrency": { "type": "string" }, "reportingPeriodStart": { "type": "string", "format": "date" }, "reportingPeriodEnd": { "type": "string", "format": "date" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiContactsByIdCommunicationsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "channel": { "type": "string" }, "direction": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "relatedDoc": { "type": "string" }, "status": { "type": "string" }, "errorMessage": { "type": "string" }, "occurredAt": { "type": "string" }, "createdAt": { "type": "string" } } }, "PostApiContactsByIdCustomerPortalRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "PostApiContactsByIdPeopleRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "includeInStatements": { "type": "boolean" } } }, "PostApiContactsByIdPeopleResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "includeInStatements": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiContactsByIdSitesRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "label": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "null" }, "suburb": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "province": { "type": "string" }, "isDefault": { "type": "boolean" } } }, "PostApiContactsByIdSitesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "label": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "suburb": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "province": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "locationSource": { "type": "string" }, "isDefault": { "type": "boolean" } } }, "PostApiContactsMergeResponseMergesItemMoved": { "description": "Shared by 2 operations.", "type": "object", "properties": { "invoices": { "type": "integer" } } }, "PostApiContactsOwnershipRegisterResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "juristic": { "type": "boolean" }, "surname": { "type": "string" }, "names": { "type": "string" }, "idNumber": { "type": "string" }, "saCitizen": { "type": "boolean" }, "nationality": { "type": "string" }, "countryOfResidence": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "interestTypes": { "type": "array", "items": { "type": "string" } }, "percentage": { "type": "number" }, "physicalAddress": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "postalCode": { "type": "string" }, "postalAddress": { "type": "string" }, "securitiesClass": { "type": "string" }, "securitiesCount": { "type": "number" }, "certificateNumber": { "type": "string" }, "amountPaid": { "type": "number" }, "acquiredOn": { "type": "string", "format": "date" }, "ceasedOn": { "type": "null" }, "active": { "type": "boolean" } } }, "PostApiCrmAttachmentsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "attachmentId": { "type": "string" }, "label": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "url": { "type": "string" }, "createdAt": { "type": "string" }, "createdByName": { "type": "string" } } }, "PostApiCrmCampaignsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "name": { "type": "string" }, "channel": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "budget": { "type": "number" }, "spend": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "targetAudience": { "type": "string" }, "notes": { "type": "string" } } }, "PostApiCrmCampaignsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "channel": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "budget": { "type": "number" }, "spend": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "targetAudience": { "type": "string" }, "notes": { "type": "string" }, "leadCount": { "type": "integer" }, "convertedLeadCount": { "type": "integer" }, "opportunityCount": { "type": "integer" }, "wonCount": { "type": "integer" }, "wonRevenue": { "type": "number" }, "weightedPipeline": { "type": "number" }, "roiPct": { "type": "number" }, "costPerLead": { "type": "number" }, "conversionRatePct": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiCrmEmailsResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "activityType": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "completedAt": { "type": "string" }, "isOverdue": { "type": "boolean" }, "ownerUserId": { "type": "string" }, "ownerName": { "type": "string" }, "leadId": { "type": "string" }, "leadName": { "type": "string" }, "opportunityId": { "type": "string" }, "opportunityName": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "outcome": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiCrmLeadsResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "companyName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "ownerUserId": { "type": "string" }, "ownerName": { "type": "string" }, "estimatedValue": { "type": "number" }, "currency": { "type": "string" }, "campaignId": { "type": "string" }, "campaignName": { "type": "string" }, "notes": { "type": "string" }, "convertedContactId": { "type": "string" }, "convertedAt": { "type": "string" }, "lostReason": { "type": "string" }, "activityCount": { "type": "integer" }, "openTaskCount": { "type": "integer" }, "lastActivityAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiCrmOpportunitiesResponse": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "leadId": { "type": "string" }, "stageId": { "type": "string" }, "stageName": { "type": "string" }, "stageIsWon": { "type": "boolean" }, "stageIsLost": { "type": "boolean" }, "ownerUserId": { "type": "string" }, "ownerName": { "type": "string" }, "value": { "type": "number" }, "currency": { "type": "string" }, "probability": { "type": "number" }, "weightedValue": { "type": "number" }, "expectedCloseDate": { "type": "string", "format": "date" }, "source": { "type": "string" }, "status": { "type": "string" }, "lostReason": { "type": "string" }, "closedAt": { "type": "string" }, "campaignId": { "type": "string" }, "campaignName": { "type": "string" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponseLinesItem" } }, "lineCount": { "type": "integer" }, "totals": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponseTotals" }, "decision": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponseDecision" }, "ageDays": { "type": "integer" }, "activityCount": { "type": "integer" }, "openTaskCount": { "type": "integer" }, "nextActivityDue": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiCrmOpportunitiesResponseDecision": { "description": "Shared by 7 operations.", "type": "object", "properties": { "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "status": { "type": "string" }, "decidedAt": { "type": "string" }, "decidedByName": { "type": "string" }, "declineReason": { "type": "string" }, "awaitingDecision": { "type": "boolean" } } }, "PostApiCrmOpportunitiesResponseLinesItem": { "description": "Shared by 8 operations.", "type": "object", "properties": { "id": { "type": "string" }, "lineNumber": { "type": "integer" }, "description": { "type": "string" }, "kind": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "productCode": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "unitCost": { "type": "number" }, "discountRate": { "type": "number" }, "discountFixed": { "type": "number" }, "discountType": { "type": "string" }, "vatRate": { "type": "number" }, "vatInclusive": { "type": "boolean" }, "notes": { "type": "string" }, "lineSubtotal": { "type": "number" }, "discountAmount": { "type": "number" }, "vatAmount": { "type": "number" }, "lineTotal": { "type": "number" } } }, "PostApiCrmOpportunitiesResponseTotals": { "description": "Shared by 7 operations.", "type": "object", "properties": { "currency": { "type": "string" }, "subtotal": { "type": "number" }, "discountTotal": { "type": "number" }, "vatTotal": { "type": "number" }, "netValue": { "type": "number" }, "grossValue": { "type": "number" }, "lineCount": { "type": "integer" }, "margin": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponseTotalsMargin" } } }, "PostApiCrmOpportunitiesResponseTotalsMargin": { "description": "Shared by 7 operations.", "type": "object", "properties": { "revenue": { "type": "number" }, "cost": { "type": "number" }, "profit": { "type": "number" }, "marginPct": { "type": "number" }, "costKnownForAllLines": { "type": "boolean" } } }, "PostApiCrmPipelinesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sortOrder": { "type": "integer" }, "isDefault": { "type": "boolean" }, "openDeals": { "type": "integer" } } }, "PostApiCrmStagesResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sortOrder": { "type": "integer" }, "defaultProbability": { "type": "number" }, "isWon": { "type": "boolean" }, "isLost": { "type": "boolean" }, "isActive": { "type": "boolean" } } }, "PostApiCrmTargetsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "ownerUserId": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "targetValue": { "type": "number" }, "currency": { "type": "string" }, "notes": { "type": "string" } } }, "PostApiCrmTargetsResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "ownerUserId": { "type": "string" }, "ownerName": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "targetValue": { "type": "number" }, "currency": { "type": "string" }, "notes": { "type": "string" }, "actualValue": { "type": "number" }, "attainmentPct": { "type": "number" }, "remaining": { "type": "number" }, "weightedForecast": { "type": "number" }, "isCurrent": { "type": "boolean" } } }, "PostApiDataBackupsByIdRestoreResponseByTable": { "description": "Shared by 2 operations.", "type": "object", "properties": { "invoices": { "type": "integer" }, "invoice_lines": { "type": "integer" } } }, "PostApiEmployeesByIdTaxDirectivesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "directiveNumber": { "type": "string" }, "percent": { "type": "number" }, "amount": { "type": "number" }, "validFrom": { "type": "string", "format": "date" }, "validTo": { "type": "string", "format": "date" }, "taxYearEnd": { "type": "integer" } } }, "PostApiEmployeesResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "documentLanguage": { "type": "string" }, "id": { "type": "string" }, "employeeNumber": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "idNumber": { "type": "string" }, "passportNumber": { "type": "string" }, "passportCountry": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "addressCountry": { "type": "string" }, "asylumPermitNumber": { "type": "string" }, "natureOfPerson": { "type": "string" }, "userId": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date" }, "employmentType": { "type": "string" }, "contractorWorksAtPremises": { "type": "boolean" }, "contractorIsSupervised": { "type": "boolean" }, "contractorHasThreeEmployees": { "type": "boolean" }, "contractorNonResident": { "type": "boolean" }, "irp30Number": { "type": "string" }, "irp30ValidTo": { "type": "string", "format": "date" }, "pspRegistrationType": { "type": "string" }, "pspRegistrationNumber": { "type": "string" }, "noOtherEmployerDeclaration": { "type": "boolean" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "terminationReason": { "type": "string" }, "terminated": { "type": "boolean" }, "jobTitle": { "type": "string" }, "department": { "type": "string" }, "costCentreId": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "bankName": { "type": "string" }, "bankAccountNumber": { "type": "string" }, "bankBranchCode": { "type": "string" }, "bankAccountType": { "type": "string" }, "paymentMethod": { "type": "string" }, "secondBankName": { "type": "string" }, "secondBankAccountNumber": { "type": "string" }, "secondBankBranchCode": { "type": "string" }, "secondBankAccountType": { "type": "string" }, "splitAmount": { "type": "number" }, "splitPercent": { "type": "number" }, "minimumWageExemption": { "type": "string" }, "minimumWageExemptionUntil": { "type": "string", "format": "date" }, "learnershipRegistrationNumber": { "type": "string" }, "learnershipNqfLevel": { "type": "integer" }, "learnershipStart": { "type": "string", "format": "date" }, "learnershipEnd": { "type": "string", "format": "date" }, "learnershipDisability": { "type": "boolean" }, "learnershipCompletedOn": { "type": "string", "format": "date" }, "learnershipCreditsEarned": { "type": "integer" }, "epwpWorker": { "type": "boolean" }, "prescribedOfficer": { "type": "boolean" }, "taxNumber": { "type": "string" }, "uifLiable": { "type": "boolean" }, "payFrequency": { "type": "string" }, "basicSalary": { "type": "number" }, "travelAllowance": { "type": "number" }, "pensionContribution": { "type": "number" }, "medicalAidContribution": { "type": "number" }, "medicalAidMembers": { "type": "integer" }, "travelInclusionRate": { "type": "number" }, "openingYtdTaxYearEnd": { "type": "integer" }, "openingYtdRemuneration": { "type": "number" }, "openingYtdPaye": { "type": "number" }, "openingYtdAnnualPayments": { "type": "number" }, "openingYtdPayeOnAnnualPayments": { "type": "number" }, "leaveBalances": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiEmployeesResponseLeaveBalancesItem" } }, "leaveDaysPerWeek": { "type": "integer" }, "leaveWorksSundays": { "type": "boolean" }, "leaveWeekdays": { "type": "array", "items": { "type": "integer" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiEmployeesResponseLeaveBalancesItem": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "employeeId": { "type": "string" }, "leaveType": { "type": "string" }, "balanceDays": { "type": "number" }, "takenDays": { "type": "number" } } }, "PostApiExpensesByIdPayRequest": { "description": "Shared by 3 operations.", "type": "object", "properties": { "bankAccountId": { "type": "string" }, "date": { "type": "string", "format": "date" } } }, "PostApiExpensesCategoriesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": "string" }, "sortOrder": { "type": "integer" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "productCount": { "type": "integer" } } }, "PostApiExpensesClaimRunsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "payDate": { "type": "string", "format": "date" }, "bankAccountId": { "type": "string" }, "bankAccountName": { "type": "string" }, "total": { "type": "number" }, "claimCount": { "type": "integer" }, "employeeCount": { "type": "integer" }, "createdAt": { "type": "string" } } }, "PostApiExpensesReceiptsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "receiptUrl": { "type": "string" }, "contentType": { "type": "string" }, "base64": { "type": "string" } } }, "PostApiFixedAssetsDepreciationRunRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "period": { "type": "string" } } }, "PostApiFixedAssetsResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "assetNumber": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "assetClass": { "type": "string" }, "assetClassLabel": { "type": "string" }, "acquisitionDate": { "type": "string", "format": "date" }, "cost": { "type": "number" }, "residualValue": { "type": "number" }, "usefulLifeMonths": { "type": "integer" }, "usefulLifeReliable": { "type": "boolean" }, "method": { "type": "string" }, "ratePercent": { "type": "number" }, "accumulatedDepreciation": { "type": "number" }, "bookValue": { "type": "number" }, "depreciatedTo": { "type": "string", "format": "date" }, "status": { "type": "string" }, "disposalDate": { "type": "string", "format": "date" }, "disposalProceeds": { "type": "number" }, "serialNumber": { "type": "string" }, "location": { "type": "string" }, "costCentreId": { "type": "string" }, "costCentreCode": { "type": "string" }, "supplierContactId": { "type": "string" }, "notes": { "type": "string" }, "monthsRemaining": { "type": "integer" } } }, "PostApiInboxReadRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } } } }, "PostApiIntercompanyTransactionsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "fromCompanyId": { "type": "string" }, "toCompanyId": { "type": "string" }, "transactionDate": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "exchangeRate": { "type": "number" }, "accountIdFrom": { "type": "string", "format": "date" }, "accountIdTo": { "type": "string", "format": "date" }, "kind": { "type": "string" }, "sellerCost": { "type": "number" }, "buyerHeldPercent": { "type": "number" }, "buyerAssetId": { "type": "string" }, "clientId": { "type": "string" } } }, "PostApiIntercompanyTransactionsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "fromCompanyId": { "type": "string" }, "toCompanyId": { "type": "string" }, "transactionDate": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "exchangeRate": { "type": "number" }, "accountIdFrom": { "type": "string", "format": "date" }, "accountIdTo": { "type": "string", "format": "date" }, "status": { "type": "string" }, "settledOn": { "type": "string", "format": "date" }, "settledAt": { "type": "string" }, "settledByName": { "type": "string" }, "settlementReference": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "kind": { "type": "string" } } }, "PostApiInventoryAdjustResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "costPrice": { "type": "number" }, "sellPrice": { "type": "number" }, "vatRate": { "type": "number" }, "stockQty": { "type": "number" }, "reorderPoint": { "type": "number" }, "unit": { "type": "string" }, "qtyPrecision": { "type": "integer" }, "barcode": { "type": "string" }, "costingMethod": { "type": "string" }, "isTracked": { "type": "boolean" }, "stockValue": { "type": "number" }, "tracksSerials": { "type": "boolean" }, "warrantyMonths": { "type": "integer" }, "imageIcon": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiInventoryAdjustmentReasonsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "label": { "type": "string" } } }, "PostApiInventoryBatchesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "locationId": { "type": "string" }, "batchNumber": { "type": "string" }, "supplier": { "type": "string" }, "receivedDate": { "type": "string", "format": "date" }, "expiryDate": { "type": "string", "format": "date" }, "qtyReceived": { "type": "number" }, "qtyRemaining": { "type": "number" }, "unitCost": { "type": "number" }, "notes": { "type": "string" }, "createdAt": { "type": "string" } } }, "PostApiInventoryBomsResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "variantId": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "outputQty": { "type": "number" }, "labourCost": { "type": "number" }, "overheadCost": { "type": "number" }, "status": { "type": "string" }, "notes": { "type": "string" }, "lineCount": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBomResponseLinesItem" } }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" }, "createdAt": { "type": "string" }, "submittedAt": { "type": "string" }, "submittedByName": { "type": "string" }, "approvedAt": { "type": "string" }, "approvedByName": { "type": "string" }, "decisionNote": { "type": "string" }, "decidedAt": { "type": "string" }, "decidedByName": { "type": "string" } } }, "PostApiInventoryCategoriesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiInventoryDisassembliesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "bomId": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "qty": { "type": "number" }, "parentValue": { "type": "number" }, "partsValue": { "type": "number" }, "residue": { "type": "number" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "brokenAt": { "type": "string" }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryDisassembliesResponsePartsItem" } } } }, "PostApiInventoryDisassembliesResponsePartsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "productName": { "type": "string" }, "qtyRecovered": { "type": "number" }, "unitCost": { "type": "number" }, "value": { "type": "number" }, "batchId": { "type": "string" } } }, "PostApiInventoryLocationsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "type": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiInventoryPriceListsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "name": { "type": "string" } } }, "PostApiInventoryPriceListsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "companyId": { "type": "string" }, "priceCount": { "type": "integer" }, "customerCount": { "type": "integer" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiInventoryProductsByIdImagesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "base64": { "type": "string" }, "url": { "type": "string" } } }, "PostApiInventoryProductsRequestUnits": { "description": "Shared by 2 operations.", "type": "object", "properties": { "bag": { "type": "number" } } }, "PostApiInventoryProductsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "costPrice": { "type": "number" }, "sellPrice": { "type": "number" }, "vatRate": { "type": "number" }, "stockQty": { "type": "number" }, "reorderPoint": { "type": "number" }, "unit": { "type": "string" }, "units": { "$ref": "#/components/schemas/GetApiPayrollYtdResponseTotals" }, "qtyPrecision": { "type": "integer" }, "barcode": { "type": "string" }, "weightKg": { "type": "number" }, "volumeM3": { "type": "number" }, "unitsPerPallet": { "type": "number" }, "costingMethod": { "type": "string" }, "isTracked": { "type": "boolean" }, "stockValue": { "type": "number" }, "tracksSerials": { "type": "boolean" }, "warrantyMonths": { "type": "integer" }, "isSellable": { "type": "boolean" }, "imageIcon": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiInventorySerialsByIdScrapRequest": { "description": "Shared by 3 operations.", "type": "object", "properties": { "notes": { "type": "string" } } }, "PostApiInventoryStockTakesResponse": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" }, "lineCount": { "type": "integer" }, "totalVariance": { "type": "number" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryStockTakesResponseLinesItem" } } } }, "PostApiInventoryStockTakesResponseLinesItem": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "sku": { "type": "string" }, "expectedQty": { "type": "number" }, "countedQty": { "type": "number" }, "variance": { "type": "number" } } }, "PostApiInventoryTransferResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "productId": { "type": "string" }, "fromLocationId": { "type": "string" }, "toLocationId": { "type": "string" }, "qty": { "type": "number" }, "reference": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiInventoryTransfersByIdCancelResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "qty": { "type": "number" }, "tenantId": { "type": "string" }, "productId": { "type": "string" }, "fromLocationId": { "type": "string" }, "toLocationId": { "type": "string" }, "reference": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiInventoryVariantsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "attributes": { "type": "string" }, "costPrice": { "type": "number" }, "sellPrice": { "type": "number" }, "stockQty": { "type": "number" }, "barcode": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" } } }, "PostApiInvoiceTemplatesRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "primaryColour": { "type": "string" } } }, "PostApiInvoiceTemplatesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "primaryColour": { "type": "string" } } }, "PostApiInvoicesByIdApplyCreditResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "documentType": { "type": "string" }, "invoiceNumber": { "type": "string" }, "status": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "deliveryDate": { "type": "string", "format": "date" }, "expectedPaymentDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "exchangeRate": { "type": "number" }, "subtotal": { "type": "number" }, "discountTotal": { "type": "number" }, "vatTotal": { "type": "number" }, "total": { "type": "number" }, "amountPaid": { "type": "number" }, "amountDue": { "type": "number" }, "vatRegistered": { "type": "boolean" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "terms": { "type": "string" }, "sourceDocumentId": { "type": "string" }, "decidedAt": { "type": "string" }, "decidedByName": { "type": "string" }, "declineReason": { "type": "string" }, "lastSendChannel": { "type": "string" }, "lastSendDelivered": { "type": "boolean" }, "lastSendError": { "type": "string" }, "lastSendAt": { "type": "string" }, "costCentreId": { "type": "string" }, "stockWarnings": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponseLinesItem" } }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponsePaymentsItem" } }, "reminders": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInvoicesByIdApplyCreditResponseRemindersItem" } }, "contactRemindersPaused": { "type": "boolean" }, "tcs": { "type": "string" }, "bankDetails": { "type": "string" }, "footer": { "type": "string" }, "deposit": { "$ref": "#/components/schemas/PostApiInvoicesRequestDeposit" }, "picking": { "$ref": "#/components/schemas/PostApiInvoicesRequestPicking" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "domesticReverseCharge": { "type": "boolean" }, "paymentGateways": { "type": "array", "items": { "type": "string" } } } }, "PostApiInvoicesByIdApplyCreditResponseRemindersItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "sentDate": { "type": "string", "format": "date" }, "channel": { "type": "string" }, "createdAt": { "type": "string" }, "status": { "type": "string" } } }, "PostApiInvoicesByIdApplyDepositRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "invoiceId": { "type": "string" } } }, "PostApiInvoicesByIdSendResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponse" }, "channel": { "type": "string" }, "delivered": { "type": "boolean" }, "deliveryError": { "type": "string" }, "portalUrl": { "type": "string" } } }, "PostApiInvoicesNumberLeasesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "leaseId": { "type": "string" }, "docType": { "type": "string" }, "nodeId": { "type": "string" }, "prefix": { "type": "string" }, "year": { "type": "integer" }, "padLength": { "type": "integer" }, "rangeStart": { "type": "integer" }, "rangeEnd": { "type": "integer" }, "nextLocal": { "type": "integer" }, "issuedAt": { "type": "string" }, "expiresAt": { "type": "string" }, "status": { "type": "string" }, "firstNumber": { "type": "string" }, "lastNumber": { "type": "string" } } }, "PostApiInvoicesPdfRequestClient": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "vatNumber": { "type": "string" }, "email": { "type": "string" }, "registrationNumber": { "type": "string" } } }, "PostApiInvoicesRequestCustomFields": { "description": "Shared by 5 operations.", "type": "object", "properties": {} }, "PostApiInvoicesRequestDeposit": { "description": "Shared by 12 operations.", "type": "object", "properties": { "percent": { "type": "number" }, "amount": { "type": "number" }, "appliedTo": { "type": "string", "format": "date" } } }, "PostApiInvoicesRequestLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "discountRate": { "type": "number" }, "discountFixed": { "type": "number" }, "discountType": { "type": "string" }, "vatRate": { "type": "number" }, "vatInclusive": { "type": "boolean" }, "accountId": { "type": "string" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "kind": { "type": "string" }, "productCode": { "type": "string" }, "warehouseBin": { "type": "string" } } }, "PostApiInvoicesRequestPicking": { "description": "Shared by 12 operations.", "type": "object", "properties": { "warehouse": { "type": "string" }, "picker": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInvoicesRequestPickingLinesItem" } } } }, "PostApiInvoicesRequestPickingLinesItem": { "description": "Shared by 12 operations.", "type": "object", "properties": { "idx": { "type": "integer" }, "picked": { "type": "boolean" } } }, "PostApiJobCardsByIdChecklistsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "jobNumber": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "title": { "type": "string" }, "workRequested": { "type": "string" }, "siteAddress": { "type": "string" }, "siteContactName": { "type": "string" }, "siteContactPhone": { "type": "string" }, "priority": { "type": "string" }, "status": { "type": "string" }, "scheduledStart": { "type": "string", "format": "date" }, "scheduledEnd": { "type": "string", "format": "date" }, "actualStart": { "type": "string", "format": "date" }, "actualEnd": { "type": "string", "format": "date" }, "quotedAmount": { "type": "number" }, "currency": { "type": "string" }, "sourceQuoteId": { "type": "string" }, "sourceQuoteNumber": { "type": "string" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "invoicedAt": { "type": "string" }, "completedAt": { "type": "string" }, "signOffName": { "type": "string" }, "signOffRole": { "type": "string" }, "signOffSignature": { "type": "string" }, "signOffSignatureAttachmentId": { "type": "string" }, "signOffNotes": { "type": "string" }, "signOffAt": { "type": "string" }, "notes": { "type": "string" }, "createdAt": { "type": "string" }, "technicians": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponseTechniciansItem" } }, "labour": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsByIdChecklistsResponseLabourItem" } }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponsePartsItem" } }, "costs": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponseCostsItem" } }, "statusHistory": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponseStatusHistoryItem" } }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponsePhotosItem" } }, "checklists": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsByIdChecklistsResponseChecklistsItem" } }, "costing": { "$ref": "#/components/schemas/PostApiJobCardsResponseCosting" }, "allowedNextStatuses": { "type": "array", "items": { "type": "string" } } } }, "PostApiJobCardsByIdChecklistsResponseChecklistsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "templateId": { "type": "string" }, "name": { "type": "string" }, "certificateTitle": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsByIdChecklistsResponseChecklistsItemItemsItem" } } } }, "PostApiJobCardsByIdChecklistsResponseChecklistsItemItemsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "required": { "type": "boolean" }, "ticked": { "type": "boolean" }, "value": { "type": "string" }, "answeredBy": { "type": "string" }, "answeredAt": { "type": "string" } } }, "PostApiJobCardsByIdChecklistsResponseLabourItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "technicianName": { "type": "string" }, "workDate": { "type": "string", "format": "date" }, "hours": { "type": "number" }, "chargeRate": { "type": "number" }, "costRate": { "type": "number" }, "billable": { "type": "boolean" }, "notes": { "type": "string" }, "timeEntryId": { "type": "string" }, "basis": { "type": "string" }, "units": { "type": "number" }, "unitLabel": { "type": "string" }, "earningTypeId": { "type": "string" }, "earningTypeName": { "type": "string" } } }, "PostApiJobCardsByIdCostsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "costType": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" }, "markupPercent": { "type": "number" }, "km": { "type": "number" }, "ratePerKm": { "type": "number" }, "billable": { "type": "boolean" }, "supplierContactId": { "type": "string" }, "incurredOn": { "type": "string", "format": "date" } } }, "PostApiJobCardsByIdPartsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "description": { "type": "string" }, "partCode": { "type": "string" }, "qty": { "type": "number" }, "unitCost": { "type": "number" }, "unitPrice": { "type": "number" }, "billable": { "type": "boolean" }, "locationId": { "type": "string" } } }, "PostApiJobCardsChecklistTemplatesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsChecklistTemplatesResponseItemsItem" } }, "certificateTitle": { "type": "string" } } }, "PostApiJobCardsChecklistTemplatesResponseItemsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "required": { "type": "boolean" } } }, "PostApiJobCardsMaintenanceRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "contactId": { "type": "string" }, "title": { "type": "string" }, "workRequested": { "type": "string" }, "siteAddress": { "type": "string" }, "siteContactName": { "type": "string" }, "siteContactPhone": { "type": "string" }, "priority": { "type": "string" }, "cadence": { "type": "string" }, "anchorDate": { "type": "string", "format": "date" }, "endsOn": { "type": "string", "format": "date" }, "active": { "type": "boolean" }, "leadUserId": { "type": "string" }, "notes": { "type": "string" }, "serialId": { "type": "string" }, "serialNumber": { "type": "string" }, "slaTargets": { "$ref": "#/components/schemas/PostApiJobCardsMaintenanceRequestSlaTargets" }, "businessHours": { "$ref": "#/components/schemas/PostApiJobCardsMaintenanceRequestBusinessHours" } } }, "PostApiJobCardsMaintenanceRequestBusinessHours": { "description": "Shared by 2 operations.", "type": "object", "properties": { "open": { "type": "string" }, "close": { "type": "string" }, "days": { "type": "array", "items": { "type": "integer" } }, "skipPublicHolidays": { "type": "boolean" } } }, "PostApiJobCardsMaintenanceRequestSlaTargets": { "description": "Shared by 2 operations.", "type": "object", "properties": { "urgent": { "$ref": "#/components/schemas/PostApiJobCardsMaintenanceRequestSlaTargetsUrgent" } } }, "PostApiJobCardsMaintenanceRequestSlaTargetsUrgent": { "description": "Shared by 2 operations.", "type": "object", "properties": { "respondMinutes": { "type": "integer" }, "resolveMinutes": { "type": "integer" } } }, "PostApiJobCardsMaintenanceResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "title": { "type": "string" }, "workRequested": { "type": "string" }, "siteAddress": { "type": "string" }, "siteContactName": { "type": "string" }, "siteContactPhone": { "type": "string" }, "priority": { "type": "string" }, "cadence": { "type": "string" }, "cadenceLabel": { "type": "string" }, "anchorDate": { "type": "string", "format": "date" }, "endsOn": { "type": "string", "format": "date" }, "active": { "type": "boolean" }, "leadUserId": { "type": "string" }, "leadUserName": { "type": "string" }, "lastRaisedOn": { "type": "string", "format": "date" }, "nextDueOn": { "type": "string", "format": "date" }, "visitsOwed": { "type": "integer" }, "visitsRaised": { "type": "integer" }, "notes": { "type": "string" } } }, "PostApiJobCardsResponse": { "description": "Shared by 22 operations.", "type": "object", "properties": { "id": { "type": "string" }, "jobNumber": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "title": { "type": "string" }, "workRequested": { "type": "string" }, "siteAddress": { "type": "string" }, "siteContactName": { "type": "string" }, "siteContactPhone": { "type": "string" }, "priority": { "type": "string" }, "status": { "type": "string" }, "scheduledStart": { "type": "string", "format": "date" }, "scheduledEnd": { "type": "string", "format": "date" }, "actualStart": { "type": "string", "format": "date" }, "actualEnd": { "type": "string", "format": "date" }, "quotedAmount": { "type": "number" }, "currency": { "type": "string" }, "sourceQuoteId": { "type": "string" }, "sourceQuoteNumber": { "type": "string" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "invoicedAt": { "type": "string" }, "completedAt": { "type": "string" }, "signOffName": { "type": "string" }, "signOffRole": { "type": "string" }, "signOffSignature": { "type": "string" }, "signOffSignatureAttachmentId": { "type": "string" }, "signOffNotes": { "type": "string" }, "signOffAt": { "type": "string" }, "notes": { "type": "string" }, "createdAt": { "type": "string" }, "technicians": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponseTechniciansItem" } }, "labour": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponseLabourItem" } }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponsePartsItem" } }, "costs": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponseCostsItem" } }, "statusHistory": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponseStatusHistoryItem" } }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponsePhotosItem" } }, "costing": { "$ref": "#/components/schemas/PostApiJobCardsResponseCosting" }, "allowedNextStatuses": { "type": "array", "items": { "type": "string" } } } }, "PostApiJobCardsResponseCosting": { "description": "Shared by 24 operations.", "type": "object", "properties": { "labourHours": { "type": "number" }, "labourCost": { "type": "number" }, "labourBillable": { "type": "number" }, "partsCost": { "type": "number" }, "partsBillable": { "type": "number" }, "otherCost": { "type": "number" }, "otherBillable": { "type": "number" }, "actualCost": { "type": "number" }, "billableValue": { "type": "number" }, "quotedAmount": { "type": "number" }, "quoteVariance": { "type": "number" }, "margin": { "type": "number" }, "marginPercent": { "type": "number" } } }, "PostApiJobCardsResponseCostsItem": { "description": "Shared by 24 operations.", "type": "object", "properties": { "id": { "type": "string" }, "costType": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" }, "markupPercent": { "type": "number" }, "km": { "type": "number" }, "ratePerKm": { "type": "number" }, "billable": { "type": "boolean" }, "supplierContactId": { "type": "string" }, "supplierName": { "type": "string" }, "incurredOn": { "type": "string", "format": "date" }, "sourceExpenseId": { "type": "string" }, "sourceBillId": { "type": "string" }, "sourceReference": { "type": "string" } } }, "PostApiJobCardsResponseLabourItem": { "description": "Shared by 22 operations.", "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "technicianName": { "type": "string" }, "workDate": { "type": "string", "format": "date" }, "hours": { "type": "number" }, "chargeRate": { "type": "number" }, "costRate": { "type": "number" }, "billable": { "type": "boolean" }, "notes": { "type": "string" }, "timeEntryId": { "type": "string" } } }, "PostApiJobCardsResponsePartsItem": { "description": "Shared by 24 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "partCode": { "type": "string" }, "qty": { "type": "number" }, "unitCost": { "type": "number" }, "unitPrice": { "type": "number" }, "billable": { "type": "boolean" }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "issued": { "type": "boolean" }, "issuedAt": { "type": "string" }, "issuedQty": { "type": "number" }, "stockMovementId": { "type": "string" }, "stockTracked": { "type": "boolean" } } }, "PostApiJobCardsResponsePhotosItem": { "description": "Shared by 25 operations.", "type": "object", "properties": { "id": { "type": "string" }, "attachmentId": { "type": "string" }, "phase": { "type": "string" }, "caption": { "type": "string" }, "sequence": { "type": "integer" }, "takenByName": { "type": "string" }, "takenAt": { "type": "string" } } }, "PostApiJobCardsResponseStatusHistoryItem": { "description": "Shared by 24 operations.", "type": "object", "properties": { "fromStatus": { "type": "string" }, "toStatus": { "type": "string" }, "note": { "type": "string" }, "changedByName": { "type": "string" }, "at": { "type": "string" } } }, "PostApiJobCardsResponseTechniciansItem": { "description": "Shared by 24 operations.", "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "isLead": { "type": "boolean" } } }, "PostApiLandedCostsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "clientId": { "type": "string" }, "docketNumber": { "type": "string" }, "docketDate": { "type": "string", "format": "date" }, "description": { "type": "string" }, "vesselOrWaybill": { "type": "string" }, "customsMrn": { "type": "string" }, "allocationMethod": { "type": "string" }, "notes": { "type": "string" }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLandedCostsRequestChargesItem" } }, "goodsReceiptIds": { "type": "array", "items": { "type": "string" } } } }, "PostApiLandedCostsRequestChargesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "chargeType": { "type": "string" }, "description": { "type": "string" }, "supplierContactId": { "type": "string" }, "billId": { "type": "string" }, "amount": { "type": "number" }, "capitalise": { "type": "boolean" }, "expenseAccountCode": { "type": "string" } } }, "PostApiLandedCostsResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "docketNumber": { "type": "string" }, "docketDate": { "type": "string", "format": "date" }, "description": { "type": "string" }, "vesselOrWaybill": { "type": "string" }, "customsMrn": { "type": "string" }, "allocationMethod": { "type": "string" }, "status": { "type": "string" }, "totalCharges": { "type": "number" }, "totalCapitalised": { "type": "number" }, "totalExpensed": { "type": "number" }, "totalRecoverable": { "type": "number" }, "journalId": { "type": "string" }, "postedAt": { "type": "string" }, "notes": { "type": "string" }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLandedCostsResponseChargesItem" } }, "receiptIds": { "type": "array", "items": { "type": "string" } }, "receiptNumbers": { "type": "array", "items": { "type": "string" } }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLandedCostsResponseAllocationsItem" } }, "isPreview": { "type": "boolean" }, "uncapitalised": { "type": "number" }, "warnings": { "type": "array", "items": { "type": "object" } } } }, "PostApiLandedCostsResponseAllocationsItem": { "description": "Shared by 6 operations.", "type": "object", "properties": { "goodsReceiptLineId": { "type": "string" }, "goodsReceiptId": { "type": "string" }, "receiptNumber": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "description": { "type": "string" }, "qty": { "type": "number" }, "invoiceUnitCost": { "type": "number" }, "lineValue": { "type": "number" }, "basisAmount": { "type": "number" }, "allocatedAmount": { "type": "number" }, "landedUnitCost": { "type": "number" }, "unitCostBefore": { "type": "number" }, "unitCostAfter": { "type": "number" }, "batchId": { "type": "string" }, "batchNumber": { "type": "string" }, "capitalisable": { "type": "boolean" } } }, "PostApiLandedCostsResponseChargesItem": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "chargeType": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "supplierContactId": { "type": "string" }, "supplierName": { "type": "string" }, "billId": { "type": "string" }, "amount": { "type": "number" }, "capitalise": { "type": "boolean" }, "expenseAccountCode": { "type": "string" } } }, "PostApiLeaveRequestsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "clientId": { "type": "string" }, "employeeId": { "type": "string" }, "leaveType": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "daysRequested": { "type": "number" }, "reason": { "type": "string" } } }, "PostApiLeaveRequestsResponse": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "leaveType": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "daysRequested": { "type": "number" }, "reason": { "type": "string" }, "status": { "type": "string" }, "approvedBy": { "type": "string" }, "approvedAt": { "type": "string" }, "createdAt": { "type": "string" } } }, "PostApiLedgerCostCentresResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "parentId": { "type": "string" }, "isActive": { "type": "boolean" } } }, "PostApiLedgerFxRevaluationResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "periodEnd": { "type": "string", "format": "date" }, "baseCurrency": { "type": "string" }, "netAdjustment": { "type": "number" }, "documentsRevalued": { "type": "integer" }, "journalId": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerFxRevaluationResponseLinesItem" } }, "missingRates": { "type": "array", "items": { "type": "string" } } } }, "PostApiLedgerFxRevaluationResponseLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "documentNumber": { "type": "string" }, "currency": { "type": "string" }, "outstanding": { "type": "number" }, "bookedRate": { "type": "number" }, "closingRate": { "type": "number" }, "bookedBase": { "type": "number" }, "restatedBase": { "type": "number" }, "adjustment": { "type": "number" } } }, "PostApiLedgerJournalBatchesRequestLinesItem": { "type": "object", "properties": { "journalDate": { "type": "string", "format": "date" }, "accountCode": { "type": "string" }, "description": { "type": "string" }, "debit": { "type": "number" }, "credit": { "type": "number" } } }, "PostApiLedgerJournalsRequestLinesItem": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "accountCode": { "type": "string" }, "accountName": { "type": "string" }, "description": { "type": "string" }, "debit": { "type": "number" }, "credit": { "type": "number" }, "costCentreId": { "type": "string" }, "contactId": { "type": "string" } } }, "PostApiLedgerJournalsResponse": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "journalNumber": { "type": "string" }, "journalDate": { "type": "string", "format": "date" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "reference": { "type": "string" }, "memo": { "type": "string" }, "status": { "type": "string" }, "totalDebit": { "type": "number" }, "totalCredit": { "type": "number" }, "reversedBy": { "type": "string" }, "reverses": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerJournalsRequestLinesItem" } }, "editable": { "type": "boolean" } } }, "PostApiLedgerPeriodsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "label": { "type": "string" }, "status": { "type": "string" }, "closedAt": { "type": "string" } } }, "PostApiLedgerRecurringJournalsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "memo": { "type": "string" }, "reference": { "type": "string" }, "frequency": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "nextDate": { "type": "string", "format": "date" }, "status": { "type": "string" }, "totalDebit": { "type": "number" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerRecurringJournalsResponseLinesItem" } }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerRecurringJournalsResponseRunsItem" } } } }, "PostApiLedgerRecurringJournalsResponseLinesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "accountCode": { "type": "string" }, "accountName": { "type": "string" }, "description": { "type": "string" }, "debit": { "type": "number" }, "credit": { "type": "number" }, "costCentreId": { "type": "string" }, "contactId": { "type": "string" }, "analysis2Id": { "type": "string" }, "analysis3Id": { "type": "string" } } }, "PostApiLedgerRecurringJournalsResponseRunsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "occurrenceDate": { "type": "string", "format": "date" }, "outcome": { "type": "string" }, "journalId": { "type": "string" }, "journalNumber": { "type": "string" }, "reason": { "type": "string" } } }, "PostApiLoansResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "lenderName": { "type": "string" }, "accountCode": { "type": "string" }, "principal": { "type": "number" }, "annualRatePercent": { "type": "number" }, "advanceDate": { "type": "string", "format": "date" }, "termMonths": { "type": "integer" }, "firstInstalmentDate": { "type": "string", "format": "date" }, "instalment": { "type": "number" }, "maturityDate": { "type": "string", "format": "date" }, "securityDescription": { "type": "string" }, "outstanding": { "type": "number" }, "accruedInterest": { "type": "number" }, "currentPortion": { "type": "number" }, "nonCurrentPortion": { "type": "number" }, "accruedPeriodEnds": { "type": "array", "items": { "type": "string", "format": "date" } }, "transactionCosts": { "type": "number" }, "marketRatePercent": { "type": "null" }, "lenderIsOwner": { "type": "boolean" }, "effectiveRatePercent": { "type": "number" }, "initialCarryingAmount": { "type": "number" }, "dayOneDifference": { "type": "number" }, "carryingAmount": { "type": "number" } } }, "PostApiLogisticsDriversByIdSettleRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "PostApiLogisticsDriversRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "settlementBasis": { "type": "string" }, "settlementRate": { "type": "integer" }, "supplierContactId": { "type": "string" }, "fullName": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "userId": { "type": "string" }, "employeeId": { "type": "string" }, "licenceNumber": { "type": "string" }, "licenceCode": { "type": "string" }, "licenceExpiry": { "type": "string", "format": "date" }, "prdpNumber": { "type": "string" }, "prdpCategories": { "type": "string" }, "prdpExpiry": { "type": "string", "format": "date" }, "status": { "type": "string" }, "defaultVehicleId": { "type": "string" }, "notes": { "type": "string" }, "clientId": { "type": "string" } } }, "PostApiLogisticsDriversResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "fullName": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "userId": { "type": "string" }, "employeeId": { "type": "string" }, "employeeNumber": { "type": "string" }, "licenceNumber": { "type": "string" }, "licenceCode": { "type": "string" }, "licenceExpiry": { "type": "string", "format": "date" }, "prdpNumber": { "type": "string" }, "prdpCategories": { "type": "string" }, "prdpExpiry": { "type": "string", "format": "date" }, "status": { "type": "string" }, "defaultVehicleId": { "type": "string" }, "defaultVehicleRegistration": { "type": "string" }, "notes": { "type": "string" }, "soonestDocumentExpiryDays": { "type": "integer" }, "soonestDocumentExpiryKind": { "type": "string" }, "appAccessIssued": { "type": "boolean" }, "appAccessRevokedAt": { "type": "string" }, "appLastSeenAt": { "type": "string" }, "openTrips": { "type": "integer" } } }, "PostApiLogisticsExceptionReasonsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "category": { "type": "string" }, "isFailure": { "type": "boolean" }, "isChargeable": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "active": { "type": "boolean" } } }, "PostApiLogisticsExceptionReasonsResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "label": { "type": "string" }, "category": { "type": "string" }, "isFailure": { "type": "boolean" }, "isChargeable": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "active": { "type": "boolean" } } }, "PostApiLogisticsStandingRunsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "runDays": { "type": "array", "items": { "type": "integer" } }, "name": { "type": "string" }, "vehicleId": { "type": "string" }, "driverId": { "type": "string" }, "cadence": { "type": "string" }, "startsOn": { "type": "string", "format": "date" }, "endsOn": { "type": "string", "format": "date" }, "active": { "type": "boolean" }, "notes": { "type": "string" }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLogisticsStandingRunsRequestStopsItem" } }, "clientId": { "type": "string" } } }, "PostApiLogisticsStandingRunsRequestStopsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "stopType": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "contactPhone": { "type": "string" }, "address": { "type": "string" }, "suburb": { "type": "string" }, "city": { "type": "string" }, "windowFrom": { "type": "string", "format": "date" }, "windowTo": { "type": "string", "format": "date" }, "instructions": { "type": "string" } } }, "PostApiLogisticsStandingRunsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "driverId": { "type": "string" }, "driverName": { "type": "string" }, "cadence": { "type": "string" }, "cadenceLabel": { "type": "string" }, "startsOn": { "type": "string", "format": "date" }, "endsOn": { "type": "string", "format": "date" }, "active": { "type": "boolean" }, "notes": { "type": "string" }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLogisticsStandingRunsRequestStopsItem" } }, "nextRuns": { "type": "array", "items": { "type": "string" } } } }, "PostApiLogisticsTripsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "tripDate": { "type": "string", "format": "date" }, "vehicleId": { "type": "string" }, "driverId": { "type": "string" }, "coDriverId": { "type": "string" }, "routeName": { "type": "string" }, "plannedDeparture": { "type": "string" }, "plannedReturn": { "type": "string" }, "notes": { "type": "string" }, "clientId": { "type": "string" } } }, "PostApiLogisticsTripsResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tripNumber": { "type": "string" }, "tripDate": { "type": "string", "format": "date" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "vehicleFleetNumber": { "type": "string" }, "driverId": { "type": "string" }, "driverName": { "type": "string" }, "coDriverId": { "type": "string" }, "coDriverName": { "type": "string" }, "status": { "type": "string" }, "routeName": { "type": "string" }, "plannedDeparture": { "type": "string" }, "actualDeparture": { "type": "string" }, "plannedReturn": { "type": "string" }, "actualReturn": { "type": "string" }, "startOdometerKm": { "type": "number" }, "endOdometerKm": { "type": "number" }, "odometerDistanceKm": { "type": "number" }, "trackedDistanceKm": { "type": "number" }, "fuelLitres": { "type": "number" }, "fuelCost": { "type": "number" }, "fuelExpenseId": { "type": "string" }, "notes": { "type": "string" }, "cancelledReason": { "type": "string" }, "dispatchedAt": { "type": "string" }, "completedAt": { "type": "string" }, "stopCount": { "type": "integer" }, "stopsCompleted": { "type": "integer" }, "stopsFailed": { "type": "integer" }, "stopsWithProof": { "type": "integer" }, "litresPer100Km": { "type": "number" }, "costPerDrop": { "type": "number" }, "currency": { "type": "string" }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponse" } }, "load": { "$ref": "#/components/schemas/PostApiLogisticsTripsResponseLoad" } } }, "PostApiLogisticsTripsResponseLoad": { "description": "Shared by 6 operations.", "type": "object", "properties": { "weightKg": { "type": "number" }, "volumeM3": { "type": "number" }, "pallets": { "type": "integer" }, "payloadKg": { "type": "number" }, "vehicleVolumeM3": { "type": "number" }, "vehiclePallets": { "type": "integer" }, "linesWithoutWeight": { "type": "integer" }, "warnings": { "type": "array", "items": { "type": "object" } } } }, "PostApiLogisticsVehicleServicesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "vehicleId": { "type": "string" }, "serviceOn": { "type": "string", "format": "date" }, "odometerKm": { "type": "number" }, "kind": { "type": "string" }, "kindLabel": { "type": "string" }, "description": { "type": "string" }, "expenseId": { "type": "string" }, "billId": { "type": "string" }, "purchaseLabel": { "type": "string" }, "costExVat": { "type": "number" }, "inspectionId": { "type": "string" } } }, "PostApiLogisticsVehiclesRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "registration": { "type": "string" }, "fleetNumber": { "type": "string" }, "make": { "type": "string" }, "model": { "type": "string" }, "year": { "type": "integer" }, "vehicleType": { "type": "string" }, "payloadKg": { "type": "number" }, "volumeM3": { "type": "number" }, "palletCapacity": { "type": "integer" }, "odometerKm": { "type": "number" }, "fuelType": { "type": "string" }, "tankLitres": { "type": "number" }, "licenceDiscExpiry": { "type": "string", "format": "date" }, "roadworthyExpiry": { "type": "string", "format": "date" }, "operatorCardExpiry": { "type": "string", "format": "date" }, "status": { "type": "string" }, "homeLocationId": { "type": "string" }, "fixedAssetId": { "type": "string" }, "telematicsExternalId": { "type": "string" }, "notes": { "type": "string" }, "clientId": { "type": "string" } } }, "PostApiLogisticsVehiclesResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "registration": { "type": "string" }, "fleetNumber": { "type": "string" }, "make": { "type": "string" }, "model": { "type": "string" }, "year": { "type": "integer" }, "vehicleType": { "type": "string" }, "payloadKg": { "type": "number" }, "volumeM3": { "type": "number" }, "palletCapacity": { "type": "integer" }, "odometerKm": { "type": "number" }, "fuelType": { "type": "string" }, "tankLitres": { "type": "number" }, "licenceDiscExpiry": { "type": "string", "format": "date" }, "roadworthyExpiry": { "type": "string", "format": "date" }, "operatorCardExpiry": { "type": "string", "format": "date" }, "status": { "type": "string" }, "homeLocationId": { "type": "string" }, "homeLocationName": { "type": "string" }, "fixedAssetId": { "type": "string" }, "telematicsExternalId": { "type": "string" }, "notes": { "type": "string" }, "soonestComplianceExpiryDays": { "type": "integer" }, "soonestComplianceExpiryKind": { "type": "string" }, "onTrip": { "type": "boolean" }, "currentTripId": { "type": "string" }, "currentTripNumber": { "type": "string" }, "lastPosition": { "$ref": "#/components/schemas/GetApiLogisticsBoardResponseItemLastPosition" } } }, "PostApiMileageTripsResponse": { "description": "Shared by 7 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "tripDate": { "type": "string", "format": "date" }, "origin": { "type": "string" }, "destination": { "type": "string" }, "distanceKm": { "type": "number" }, "ratePerKm": { "type": "number" }, "claimAmount": { "type": "number" }, "purpose": { "type": "string" }, "vehicle": { "type": "string" }, "status": { "type": "string" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "approvedBy": { "type": "string" }, "approvedByName": { "type": "string" }, "approvedAt": { "type": "string" }, "notes": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiMrpCalendarResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "status": { "type": "string" }, "days": { "type": "string" } } }, "PostApiMrpCheckPlansResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "minValue": { "type": "number" }, "maxValue": { "type": "number" }, "unit": { "type": "string" }, "everyHours": { "type": "integer" }, "workCentreId": { "type": "null" }, "workCentreCode": { "type": "null" }, "active": { "type": "boolean" } } }, "PostApiMrpConvertResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "requisitionIds": { "type": "array", "items": { "type": "string" } }, "requisitionNumbers": { "type": "array", "items": { "type": "string" } }, "workOrderIds": { "type": "array", "items": { "type": "string" } }, "workOrderNumbers": { "type": "array", "items": { "type": "string" } }, "convertedCount": { "type": "integer" }, "skipped": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpConvertResponseSkippedItem" } } } }, "PostApiMrpConvertResponseSkippedItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "plannedOrderId": { "type": "string" }, "productName": { "type": "string" }, "reason": { "type": "string" } } }, "PostApiMrpForecastsResponse": { "description": "Shared by 11 operations.", "type": "object", "properties": { "id": { "type": "string" } } }, "PostApiMrpProductionScheduleResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "runId": { "type": "string" }, "runNumber": { "type": "string" }, "editable": { "type": "boolean" }, "notEditableReason": { "type": "null" }, "today": { "type": "string", "format": "date" }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRunsResponseBucketsItem" } }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpProductionScheduleResponseRowsItem" } } } }, "PostApiMrpProductionScheduleResponseRowsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "qtyPrecision": { "type": "integer" }, "opening": { "type": "number" }, "weeks": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpProductionScheduleResponseRowsItemWeeksItem" } } } }, "PostApiMrpProductionScheduleResponseRowsItemWeeksItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "bucketIndex": { "type": "integer" }, "start": { "type": "string", "format": "date" }, "forecast": { "type": "number" }, "firm": { "type": "number" }, "demand": { "type": "number" }, "receipts": { "type": "number" }, "build": { "type": "number" }, "scheduled": { "type": "boolean" } } }, "PostApiMrpRoutingsByIdOperationsRequest": { "description": "Shared by 3 operations.", "type": "object", "properties": { "sequenceNo": { "type": "integer" }, "description": { "type": "string" }, "workCentreId": { "type": "string" }, "setupHours": { "type": "number" }, "runHoursPerUnit": { "type": "number" }, "isSubcontract": { "type": "boolean" }, "subcontractSupplierId": { "type": "string" }, "subcontractCostPerUnit": { "type": "number" }, "subcontractLeadDays": { "type": "integer" }, "instructions": { "type": "string" } } }, "PostApiMrpRoutingsResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "bomId": { "type": "string" }, "bomName": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string" }, "isDefault": { "type": "boolean" }, "expectedYieldPercent": { "type": "number" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" }, "notes": { "type": "string" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRoutingsResponseOperationsItem" } }, "qty": { "type": "number" }, "startedQty": { "type": "number" }, "setupHours": { "type": "number" }, "runHours": { "type": "number" }, "totalHours": { "type": "number" }, "labourCost": { "type": "number" }, "overheadCost": { "type": "number" }, "subcontractCost": { "type": "number" }, "totalCost": { "type": "number" }, "costPerUnit": { "type": "number" }, "unassignedOperationCount": { "type": "integer" } } }, "PostApiMrpRoutingsResponseOperationsItem": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "sequenceNo": { "type": "integer" }, "description": { "type": "string" }, "workCentreId": { "type": "string" }, "workCentreCode": { "type": "string" }, "workCentreName": { "type": "string" }, "setupHours": { "type": "number" }, "runHoursPerUnit": { "type": "number" }, "isSubcontract": { "type": "boolean" }, "subcontractSupplierId": { "type": "string" }, "subcontractSupplierName": { "type": "string" }, "subcontractCostPerUnit": { "type": "number" }, "subcontractLeadDays": { "type": "integer" }, "instructions": { "type": "string" }, "hoursForQty": { "type": "number" }, "costForQty": { "type": "number" } } }, "PostApiMrpRunsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "run": { "$ref": "#/components/schemas/GetApiMrpRunsResponseItem" }, "plannedOrders": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRunsResponsePlannedOrdersItem" } }, "projections": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRunsResponseProjectionsItem" } }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRunsResponseBucketsItem" } }, "unplannedDemand": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRunsResponseUnplannedDemandItem" } }, "cycles": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "capacity": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRunsResponseCapacityItem" } }, "supplyActions": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRunsResponseSupplyActionsItem" } }, "outsideWork": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRunsResponseOutsideWorkItem" } } } }, "PostApiMrpRunsResponseBucketsItem": { "description": "Shared by 5 operations.", "type": "object", "properties": { "index": { "type": "integer" }, "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" }, "label": { "type": "string" } } }, "PostApiMrpRunsResponseCapacityItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "workCentreId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "cells": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRunsResponseCapacityItemCellsItem" } } } }, "PostApiMrpRunsResponseCapacityItemCellsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "bucketIndex": { "type": "integer" }, "plannedHours": { "type": "number" }, "floorHours": { "type": "number" }, "availableHours": { "type": "number" } } }, "PostApiMrpRunsResponseOutsideWorkItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "sku": { "type": "string" }, "step": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "workOrderId": { "type": "string" }, "workOrderNumber": { "type": "string" }, "plannedOrderId": { "type": "string" }, "qty": { "type": "number" }, "unitCost": { "type": "number" }, "estimatedCost": { "type": "number" }, "releaseDate": { "type": "string", "format": "date" }, "requiredDate": { "type": "string", "format": "date" }, "leadDays": { "type": "integer" }, "status": { "type": "string" }, "requisitionNumber": { "type": "string" }, "qtyPrecision": { "type": "integer" } } }, "PostApiMrpRunsResponsePlannedOrdersItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "engineKey": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "orderType": { "type": "string" }, "lowLevelCode": { "type": "integer" }, "bucketIndex": { "type": "integer" }, "qtyNet": { "type": "number" }, "qtyOrdered": { "type": "number" }, "requiredDate": { "type": "string", "format": "date" }, "releaseDate": { "type": "string", "format": "date" }, "leadTimeDays": { "type": "integer" }, "status": { "type": "string" }, "bomId": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "unitCost": { "type": "number" }, "estimatedCost": { "type": "number" }, "exceptions": { "type": "array", "items": { "type": "string" } }, "requisitionLineId": { "type": "string" }, "requisitionNumber": { "type": "string" }, "workOrderId": { "type": "string" }, "workOrderNumber": { "type": "string" }, "pegging": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRunsResponsePlannedOrdersItemPeggingItem" } }, "onHand": { "type": "number" }, "notes": { "type": "string" } } }, "PostApiMrpRunsResponsePlannedOrdersItemPeggingItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "demandSource": { "type": "string" }, "demandRef": { "type": "string" }, "qty": { "type": "number" }, "requiredDate": { "type": "string", "format": "date" }, "parentEngineKey": { "type": "string" }, "parentProductName": { "type": "string" } } }, "PostApiMrpRunsResponseProjectionsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "lowLevelCode": { "type": "integer" }, "sourceType": { "type": "string" }, "safetyStock": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "openingOnHand": { "type": "number" }, "cells": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRunsResponseProjectionsItemCellsItem" } } } }, "PostApiMrpRunsResponseProjectionsItemCellsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "bucketIndex": { "type": "integer" }, "bucketStart": { "type": "string", "format": "date" }, "bucketEnd": { "type": "string", "format": "date" }, "grossRequirement": { "type": "number" }, "scheduledReceipts": { "type": "number" }, "plannedReceipts": { "type": "number" }, "projectedOnHand": { "type": "number" }, "netRequirement": { "type": "number" }, "plannedReleases": { "type": "number" }, "belowSafety": { "type": "boolean" } } }, "PostApiMrpRunsResponseSupplyActionsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "productName": { "type": "string" }, "sku": { "type": "string" }, "source": { "type": "string" }, "documentId": { "type": "string" }, "documentNumber": { "type": "string" }, "action": { "type": "string" }, "currentDate": { "type": "string", "format": "date" }, "suggestedDate": { "type": "string", "format": "date" }, "qty": { "type": "number" }, "suggestedQty": { "type": "number" }, "qtyPrecision": { "type": "integer" } } }, "PostApiMrpRunsResponseUnplannedDemandItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "sourceType": { "type": "string" }, "sourceRef": { "type": "string" }, "qty": { "type": "number" }, "requiredDate": { "type": "string", "format": "date" }, "bucketIndex": { "type": "integer" }, "unplanned": { "type": "boolean" } } }, "PostApiMrpWorkCentresByIdMaintenanceResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "workCentreId": { "type": "string" }, "workCentreName": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "title": { "type": "string" }, "trigger": { "type": "string" }, "cycle": { "type": "number" }, "cadence": { "type": "string" }, "downtimeHours": { "type": "number" }, "lastServiceAt": { "type": "string" }, "meter": { "type": "number" }, "due": { "type": "boolean" }, "nextDueOn": { "type": "string", "format": "date" }, "standing": { "type": "string" }, "openJobCardId": { "type": "string" }, "openJobNumber": { "type": "string" }, "openScheduledStart": { "type": "string", "format": "date" }, "active": { "type": "boolean" } } }, "PostApiMrpWorkCentresByIdUpResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "workCentreId": { "type": "string" }, "reason": { "type": "string" }, "notes": { "type": "string" }, "startedAt": { "type": "string" }, "endedAt": { "type": "string" }, "hours": { "type": "number" }, "startedByName": { "type": "string" } } }, "PostApiMrpWorkCentresRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "capacityHoursPerDay": { "type": "number" }, "machineCount": { "type": "integer" }, "efficiencyPercent": { "type": "number" }, "workingDays": { "type": "array", "items": { "type": "integer" } }, "queueDays": { "type": "integer" }, "labourRatePerHour": { "type": "number" }, "overheadRatePerHour": { "type": "number" }, "isSubcontract": { "type": "boolean" }, "observePublicHolidays": { "type": "boolean" }, "supplierContactId": { "type": "string" }, "locationId": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "type": "string" } } }, "PostApiMrpWorkCentresResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "capacityHoursPerDay": { "type": "number" }, "machineCount": { "type": "integer" }, "efficiencyPercent": { "type": "number" }, "workingDays": { "type": "array", "items": { "type": "integer" } }, "queueDays": { "type": "integer" }, "labourRatePerHour": { "type": "number" }, "overheadRatePerHour": { "type": "number" }, "isSubcontract": { "type": "boolean" }, "observePublicHolidays": { "type": "boolean" }, "supplierContactId": { "type": "string" }, "supplierName": { "type": "string" }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "type": "string" }, "dailyEffectiveHours": { "type": "number" }, "routingOperationCount": { "type": "integer" }, "openOperationCount": { "type": "integer" } } }, "PostApiPayrollAveragingAgreementsResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "templateId": { "type": "string" }, "employeeId": { "type": "string" }, "kind": { "type": "string" }, "startsOn": { "type": "string", "format": "date" }, "endsOn": { "type": "string", "format": "date" }, "averageWeeklyHours": { "type": "number" }, "overtimeWeeklyCap": { "type": "number" } } }, "PostApiPayrollBeneficiariesRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "name": { "type": "string" }, "beneficiaryType": { "type": "string" }, "accountReference": { "type": "string" }, "bankName": { "type": "string" }, "bankAccountNumber": { "type": "string" }, "bankBranchCode": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPhone": { "type": "string" }, "remittanceEmail": { "type": "string" }, "notes": { "type": "string" }, "isActive": { "type": "boolean" } } }, "PostApiPayrollBeneficiariesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "beneficiaryType": { "type": "string" }, "typeLabel": { "type": "string" }, "accountReference": { "type": "string" }, "bankName": { "type": "string" }, "bankAccountNumber": { "type": "string" }, "bankBranchCode": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPhone": { "type": "string" }, "remittanceEmail": { "type": "string" }, "notes": { "type": "string" }, "isActive": { "type": "boolean" }, "memberCount": { "type": "integer" } } }, "PostApiPayrollCostToCompanyResponseComponentsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": "number" } } }, "PostApiPayrollDeductionsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "employeeId": { "type": "string" }, "beneficiaryId": { "type": "string" }, "memberReference": { "type": "string" }, "calculation": { "type": "string" }, "employeeAmount": { "type": "number" }, "employerAmount": { "type": "number" }, "employeePercent": { "type": "number" }, "employerPercent": { "type": "number" }, "totalOwing": { "type": "number" }, "orderReference": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "isActive": { "type": "boolean" }, "notes": { "type": "string" }, "s34AgreementDocumentId": { "type": "string" }, "s34FaultConfirmed": { "type": "boolean" }, "s34ProcedureDate": { "type": "string", "format": "date" }, "s34ActualLoss": { "type": "number" }, "consentDate": { "type": "string", "format": "date" }, "consentReference": { "type": "string" }, "isFine": { "type": "boolean" } } }, "PostApiPayrollDeductionsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "beneficiaryId": { "type": "string" }, "beneficiaryName": { "type": "string" }, "beneficiaryType": { "type": "string" }, "memberReference": { "type": "string" }, "calculation": { "type": "string" }, "employeeAmount": { "type": "number" }, "employerAmount": { "type": "number" }, "employeePercent": { "type": "number" }, "employerPercent": { "type": "number" }, "totalOwing": { "type": "number" }, "totalPaid": { "type": "number" }, "outstanding": { "type": "number" }, "orderReference": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "isActive": { "type": "boolean" }, "notes": { "type": "string" }, "s34AgreementDocumentId": { "type": "string" }, "s34FaultConfirmed": { "type": "boolean" }, "s34ProcedureDate": { "type": "string", "format": "date" }, "s34ActualLoss": { "type": "number" }, "consentDate": { "type": "string", "format": "date" }, "consentReference": { "type": "string" }, "packageNotice": { "type": "string" } } }, "PostApiPayrollEarningTypesResponse": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sarsCode": { "type": "string" }, "sarsLabel": { "type": "string" }, "calculation": { "type": "string" }, "calculationLabel": { "type": "string" }, "defaultAmount": { "type": "number" }, "defaultPercent": { "type": "number" }, "defaultRate": { "type": "number" }, "unitLabel": { "type": "string" }, "active": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "notes": { "type": "string" }, "taxable": { "type": "boolean" }, "assignedCount": { "type": "integer" }, "glAccountId": { "type": "string" }, "postsToLabel": { "type": "string" }, "postsToIsDefault": { "type": "boolean" }, "problem": { "type": "string" } } }, "PostApiPayrollFringeBenefitsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "employeeId": { "type": "string" }, "benefitType": { "type": "string" }, "description": { "type": "string" }, "determinedValue": { "type": "number" }, "maintenancePlanIncluded": { "type": "boolean" }, "inputTaxClaimed": { "type": "boolean" }, "employeeBearsMaintenance": { "type": "boolean" }, "depreciationYears": { "type": "integer" }, "operatingLeaseCost": { "type": "number" }, "operatingLeaseFuelCost": { "type": "number" }, "businessUseAtLeast80": { "type": "boolean" }, "employeeConsideration": { "type": "number" }, "loanBalance": { "type": "number" }, "loanInterestPaid": { "type": "number" }, "repoRate": { "type": "number" }, "remunerationProxy": { "type": "number" }, "abatementNil": { "type": "boolean" }, "atLeastFourRooms": { "type": "boolean" }, "furnished": { "type": "boolean" }, "powerOrFuelSupplied": { "type": "boolean" }, "employerExpenditure": { "type": "number" }, "employeeRent": { "type": "number" }, "monthlyAmount": { "type": "number" }, "noValueProvision": { "type": "boolean" }, "noValueReason": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "isActive": { "type": "boolean" }, "notes": { "type": "string" } } }, "PostApiPayrollFringeBenefitsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "benefitType": { "type": "string" }, "typeLabel": { "type": "string" }, "description": { "type": "string" }, "determinedValue": { "type": "number" }, "maintenancePlanIncluded": { "type": "boolean" }, "inputTaxClaimed": { "type": "boolean" }, "employeeBearsMaintenance": { "type": "boolean" }, "depreciationYears": { "type": "integer" }, "operatingLeaseCost": { "type": "number" }, "operatingLeaseFuelCost": { "type": "number" }, "businessUseAtLeast80": { "type": "boolean" }, "employeeConsideration": { "type": "number" }, "loanBalance": { "type": "number" }, "loanInterestPaid": { "type": "number" }, "repoRate": { "type": "number" }, "remunerationProxy": { "type": "number" }, "abatementNil": { "type": "boolean" }, "atLeastFourRooms": { "type": "boolean" }, "furnished": { "type": "boolean" }, "powerOrFuelSupplied": { "type": "boolean" }, "employerExpenditure": { "type": "number" }, "employeeRent": { "type": "number" }, "monthlyAmount": { "type": "number" }, "noValueProvision": { "type": "boolean" }, "noValueReason": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "isActive": { "type": "boolean" }, "notes": { "type": "string" }, "monthlyValue": { "type": "number" }, "monthlyRemuneration": { "type": "number" }, "sourceCode": { "type": "string" }, "workings": { "type": "string" }, "issue": { "type": "string" }, "used": { "type": "boolean" } } }, "PostApiPayrollPayTemplatesByIdRatesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "employees": { "type": "integer" }, "overriddenBy": { "type": "array", "items": { "type": "string" } }, "sentence": { "type": "string" } } }, "PostApiPayrollPayTemplatesRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "name": { "type": "string" }, "payBasis": { "type": "string" }, "ordinaryHoursWeekly": { "type": "number" }, "ordinaryDaysWeekly": { "type": "integer" }, "ordinarilyWorksSundays": { "type": "boolean" }, "shiftHours": { "type": "number" }, "dayCapHours": { "type": "number" }, "fundSalaryWeeklyHours": { "type": "number" }, "fundSalaryWeeks": { "type": "number" }, "council": { "type": "string" }, "councilGrade": { "type": "string" }, "councilArea": { "type": "string" } } }, "PostApiPayrollPayTemplatesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "payBasis": { "type": "string" }, "ordinaryHoursWeekly": { "type": "number" }, "ordinaryDaysWeekly": { "type": "integer" }, "ordinarilyWorksSundays": { "type": "boolean" }, "shiftHours": { "type": "number" }, "dayCapHours": { "type": "number" }, "fundSalaryWeeklyHours": { "type": "number" }, "fundSalaryWeeks": { "type": "number" }, "agreements": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollAveragingAgreementsResponse" } }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollPayTemplatesResponseRatesItem" } }, "earnings": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollPayTemplatesResponseEarningsItem" } }, "deductions": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollPayTemplatesResponseDeductionsItem" } }, "employeeCount": { "type": "integer" } } }, "PostApiPayrollPayTemplatesResponseDeductionsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "beneficiaryId": { "type": "string" }, "beneficiaryName": { "type": "string" }, "effectiveFrom": { "type": "string", "format": "date" }, "base": { "type": "string" }, "calculation": { "type": "string" }, "employeeAmount": { "type": "number" }, "employerAmount": { "type": "number" }, "employeePercent": { "type": "number" }, "employerPercent": { "type": "number" }, "unpaidLeave": { "type": "string" } } }, "PostApiPayrollPayTemplatesResponseEarningsItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "earningTypeId": { "type": "string" }, "earningTypeName": { "type": "string" }, "effectiveFrom": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "percent": { "type": "number" }, "rate": { "type": "number" }, "units": { "type": "number" } } }, "PostApiPayrollPayTemplatesResponseRatesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "effectiveFrom": { "type": "string", "format": "date" }, "monthlySalary": { "type": "number" }, "hourlyRate": { "type": "number" } } }, "PostApiPayrollPeriodsByIdInputsPullJobsResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "source": { "type": "string" }, "counted": { "type": "integer" }, "people": { "type": "integer" }, "hours": { "type": "number" }, "skipped": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "integer" }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollPeriodsByIdInputsResponseItemsItem" } } } }, "PostApiPayrollPeriodsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "periodType": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "payDate": { "type": "string", "format": "date" } } }, "PostApiPayrollPeriodsResponse": { "description": "Shared by 8 operations.", "type": "object", "properties": { "id": { "type": "string" }, "periodType": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "payDate": { "type": "string", "format": "date" }, "status": { "type": "string" }, "grossTotal": { "type": "number" }, "payeTotal": { "type": "number" }, "uifTotal": { "type": "number" }, "sdlTotal": { "type": "number" }, "nettTotal": { "type": "number" }, "employeeCount": { "type": "integer" }, "uifEmployeeTotal": { "type": "number" }, "uifEmployerTotal": { "type": "number" }, "pensionTotal": { "type": "number" }, "medicalTotal": { "type": "number" }, "thirdPartyDeductionsTotal": { "type": "number" }, "employerRetirementTotal": { "type": "number" }, "employerMedicalTotal": { "type": "number" }, "employeeDeductionsTotal": { "type": "number" }, "employerContributionsTotal": { "type": "number" }, "costToCompanyTotal": { "type": "number" }, "deductionsReconcile": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiPayslipsByIdSendResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "payslipId": { "type": "string" }, "channel": { "type": "string" }, "delivered": { "type": "boolean" }, "deliveryError": { "type": "string" } } }, "PostApiPerDiemClaimsResponse": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "employee": { "type": "string" }, "destination": { "type": "string" }, "periodLabel": { "type": "string" }, "days": { "type": "integer" }, "ratePerDay": { "type": "number" }, "totalAmount": { "type": "number" }, "policy": { "type": "string" }, "status": { "type": "string" }, "rejectionReason": { "type": "string" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "approvedBy": { "type": "string" }, "approvedByName": { "type": "string" }, "approvedAt": { "type": "string" }, "notes": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiPerDiemRatesRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "name": { "type": "string" }, "dailyAmount": { "type": "number" } } }, "PostApiPerDiemRatesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "dailyAmount": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiPettyCashCountsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "countedAmount": { "type": "number" }, "bookAmount": { "type": "number" }, "difference": { "type": "number" }, "note": { "type": "string" }, "createdAt": { "type": "string" } } }, "PostApiPettyCashTxnsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "category": { "type": "string" }, "receipt": { "type": "boolean" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "notes": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiPosJournalsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "clientId": { "type": "string" }, "journalId": { "type": "string" }, "kind": { "type": "string" }, "journalDate": { "type": "string", "format": "date" }, "reference": { "type": "string" }, "standardRatedNetCents": { "type": "integer" }, "zeroRatedCents": { "type": "integer" }, "outputVatCents": { "type": "integer" }, "inputVatCents": { "type": "integer" }, "costOfSalesCents": { "type": "integer" } } }, "PostApiPractitionerBulkRunResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "action": { "type": "string" }, "actionTitle": { "type": "string" }, "summary": { "type": "string" }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPractitionerBulkRunResponseOutcomesItem" } } } }, "PostApiPractitionerBulkRunResponseOutcomesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } } }, "PostApiPractitionerClientsByIdAddonsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "clientTenantId": { "type": "string" }, "addonId": { "type": "string" }, "quantity": { "type": "integer" }, "addonCentsMonthly": { "type": "integer" }, "proratedCentsNow": { "type": "integer" }, "notice": { "type": "string" } } }, "PostApiPractitionerLinksResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "practitionerEmail": { "type": "string" }, "practitionerName": { "type": "string" }, "status": { "type": "string" }, "accessLevel": { "type": "string" }, "invitedAt": { "type": "string" }, "acceptedAt": { "type": "string" } } }, "PostApiPractitionerQueriesResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "subjectType": { "type": "string" }, "subjectId": { "type": "string" }, "subjectLabel": { "type": "string" }, "question": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "answer": { "type": "string" }, "askedByEmail": { "type": "string" }, "createdAt": { "type": "string" }, "answeredAt": { "type": "string" }, "resolvedAt": { "type": "string" } } }, "PostApiProcurementSupplierOffersByIdDecideRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "outcome": { "type": "string" }, "note": { "type": "string" } } }, "PostApiProcurementSupplierOffersByIdDecideResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "ok": { "type": "string" }, "message": { "type": "string" } } }, "PostApiProcurementSupplierRegistrationsByIdAcceptResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" }, "contactId": { "type": "string" }, "vendorRowCount": { "type": "integer" }, "applicantEmailed": { "type": "boolean" } } }, "PostApiPropertySalesResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "property": { "type": "string" }, "buyer": { "type": "string" }, "agreementDate": { "type": "string", "format": "date" }, "price": { "type": "number" }, "treatment": { "type": "string" }, "treatmentNote": { "type": "string" }, "heldAs": { "type": "string" }, "fixedAssetId": { "type": "null" }, "capitalGoods": { "type": "boolean" }, "residentialPriceFixed": { "type": "boolean" }, "timeOfSupply": { "type": "string", "format": "date" }, "ratePercent": { "type": "number" }, "rateReason": { "type": "string" }, "registeredOn": { "type": "null" }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPropertySalesResponsePaymentsItem" } }, "received": { "type": "number" }, "vatDeclared": { "type": "number" } } }, "PostApiPropertySalesResponsePaymentsItem": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "paidOn": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "heldInTrust": { "type": "boolean" }, "declaredOn": { "type": "string", "format": "date" }, "vatAmount": { "type": "number" } } }, "PostApiPurchaseOrdersDropShipResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "status": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "salesInvoiceId": { "type": "string" }, "salesInvoiceNumber": { "type": "string" }, "customerName": { "type": "string" }, "deliveryAddress": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "qty": { "type": "number" }, "unitCost": { "type": "number" }, "qtyDespatched": { "type": "number" }, "billId": { "type": "string" } } }, "PostApiReconciliationByIdClearRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "transactionIds": { "type": "array", "items": { "type": "string" } } } }, "PostApiRecurringByIdLeaseDepositApplyRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "invoiceId": { "type": "string" }, "on": { "type": "string", "format": "date" } } }, "PostApiRecurringByIdLeaseDepositRefundRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "bankAccountId": { "type": "string" }, "on": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "reference": { "type": "string" } } }, "PostApiRecurringRequestLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "discountRate": { "type": "number" }, "discountType": { "type": "string" }, "vatRate": { "type": "number" }, "kind": { "type": "string" }, "productId": { "type": "string" }, "vatType": { "type": "string" } } }, "PostApiRecurringResponse": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" }, "frequency": { "type": "string" }, "nextDate": { "type": "string", "format": "date" }, "active": { "type": "boolean" }, "currency": { "type": "string" }, "documentType": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "onCreate": { "type": "string" } } }, "PostApiRentalContractsByIdDepositLinkResponse": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "gateway": { "type": "string" }, "amount": { "type": "number" }, "status": { "type": "string" }, "paidAt": { "type": "string" } } }, "PostApiRentalContractsByIdReturnResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "contractNumber": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "site": { "type": "string" }, "status": { "type": "string" }, "outDate": { "type": "string", "format": "date" }, "dueBack": { "type": "string" }, "offHiredOn": { "type": "string", "format": "date" }, "delivery": { "type": "boolean" }, "collection": { "type": "boolean" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRentalContractsByIdReturnResponseLinesItem" } }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiRentalContractsByIdResponseChargesItem" } }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiRentalContractsByIdResponseStopsItem" } }, "photoCount": { "type": "integer" }, "total": { "type": "number" } } }, "PostApiRentalContractsByIdReturnResponseLinesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "hireItemId": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "quantity": { "type": "integer" }, "qtyOut": { "type": "integer" }, "qtyBack": { "type": "integer" }, "qtyMissing": { "type": "integer" }, "withCustomer": { "type": "integer" }, "toGo": { "type": "integer" }, "offHiredOn": { "type": "string", "format": "date" }, "hireCharge": { "type": "number" }, "periods": { "type": "string" } } }, "PostApiRentalItemsResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "fixedAssetId": { "type": "string" }, "assetNumber": { "type": "string" }, "name": { "type": "string" }, "itemClass": { "type": "string" }, "kind": { "type": "string" }, "quantity": { "type": "integer" }, "available": { "type": "integer" }, "reserved": { "type": "integer" }, "onHire": { "type": "integer" }, "inService": { "type": "integer" }, "lost": { "type": "integer" }, "status": { "type": "string" } } }, "PostApiRentalQuoteRequestLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "hireItemId": { "type": "string" }, "quantity": { "type": "integer" } } }, "PostApiRentedLeasesRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "contactId": { "type": "string" }, "description": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "intervalMonths": { "type": "integer" }, "rent": { "type": "number" }, "escalationPercent": { "type": "number" }, "escalationDate": { "type": "string", "format": "date" }, "escalationMonths": { "type": "integer" } } }, "PostApiRentedLeasesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "description": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "intervalMonths": { "type": "integer" }, "rent": { "type": "number" }, "escalationPercent": { "type": "number" }, "escalationDate": { "type": "string", "format": "date" }, "escalationMonths": { "type": "integer" }, "levelRent": { "type": "number" }, "cycles": { "type": "integer" }, "bills": { "type": "integer" }, "billed": { "type": "number" }, "expensed": { "type": "number" }, "accrued": { "type": "number" }, "kind": { "type": "string" }, "loanId": { "type": "null" }, "fixedAssetId": { "type": "null" } } }, "PostApiReportPacksRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "name": { "type": "string" }, "coverTitle": { "type": "string" }, "commentary": { "type": "string" }, "reports": { "type": "array", "items": { "type": "string" } }, "period": { "type": "string" } } }, "PostApiReportPacksResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "coverTitle": { "type": "string" }, "commentary": { "type": "string" }, "reports": { "type": "array", "items": { "type": "string" } }, "period": { "type": "string" } } }, "PostApiReportsCustomRequest": { "description": "Shared by 4 operations.", "type": "object", "properties": { "name": { "type": "string" }, "periodGrouping": { "type": "string" }, "dimensions": { "type": "array", "items": { "type": "string" } }, "measures": { "type": "array", "items": { "type": "string" } }, "filters": { "$ref": "#/components/schemas/PostApiReportsCustomRequestFilters" } } }, "PostApiReportsCustomRequestFilters": { "description": "Shared by 4 operations.", "type": "object", "properties": { "costCentreId": { "type": "string" }, "contactId": { "type": "string" }, "accountIds": { "type": "array", "items": { "type": "string" } }, "sections": { "type": "array", "items": { "type": "string" } } } }, "PostApiReportsCustomResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "definition": { "$ref": "#/components/schemas/PostApiReportsCustomRequest" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiReportsCustomRunResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "name": { "type": "string" }, "periodLabel": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiReportsCustomRunResponseColumnsItem" } }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiReportsCustomRunResponseRowsItem" } }, "totals": { "type": "array", "items": { "type": "number" } }, "reconciles": { "type": "boolean" }, "filtered": { "type": "boolean" }, "companies": { "type": "array", "items": { "type": "string" } } } }, "PostApiReportsCustomRunResponseColumnsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" } } }, "PostApiReportsCustomRunResponseRowsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string" } }, "values": { "type": "array", "items": { "type": "number" } } } }, "PostApiReportsScheduledResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "reportType": { "type": "string" }, "frequency": { "type": "string" }, "nextRun": { "type": "string" }, "recipients": { "type": "string" }, "format": { "type": "string" }, "active": { "type": "boolean" }, "lastRun": { "type": "string" }, "lastStatus": { "type": "string" } } }, "PostApiRolesRequestPermissionsItem": { "description": "Shared by 6 operations.", "type": "object", "properties": { "resource": { "type": "string" }, "action": { "type": "string" } } }, "PostApiRolesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "isSystem": { "type": "boolean" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRolesRequestPermissionsItem" } }, "userCount": { "type": "integer" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiSarsDocumentsDividendsResponseBeneficialOwnersItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "taxReferenceNumber": { "type": "string" }, "identityOrRegistrationNumber": { "type": "string" }, "countryOfResidence": { "type": "string" }, "dividendAmount": { "type": "number" }, "exemptAmount": { "type": "number" }, "exemptionGround": { "type": "string" }, "exemptionReason": { "type": "string" }, "declarationReceivedDate": { "type": "string", "format": "date" }, "treatyRatePercent": { "type": "number" }, "taxableAmount": { "type": "number" }, "ratePercent": { "type": "number" }, "taxWithheld": { "type": "number" } } }, "PostApiSarsDonationReceiptsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "receiptNumber": { "type": "string" }, "donationDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "nature": { "type": "null" }, "contactId": { "type": "string" }, "donorName": { "type": "string" }, "donorTradingName": { "type": "null" }, "donorAddress": { "type": "string" }, "donorPhone": { "type": "string" }, "donorEmail": { "type": "string" }, "donorNature": { "type": "string" }, "donorIdType": { "type": "string" }, "donorIdNumber": { "type": "string" }, "donorIdCountry": { "type": "string" }, "donorTaxNumber": { "type": "string" }, "issuedAt": { "type": "string" }, "lastSentAt": { "type": "null" }, "lastSendDelivered": { "type": "null" } } }, "PostApiSarsIrp6SubmitResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "submissionType": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "totalPaye": { "type": "number" }, "totalUif": { "type": "number" }, "totalSdl": { "type": "number" }, "totalEti": { "type": "number" }, "totalPayable": { "type": "number" }, "totalDue": { "type": "number" }, "status": { "type": "string" }, "referenceNumber": { "type": "string" }, "submittedAt": { "type": "string" }, "createdAt": { "type": "string" } } }, "PostApiSarsIt14SubmitRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "year": { "type": "integer" } } }, "PostApiSarsSubmissionsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "submissionType": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" } } }, "PostApiSarsSubmissionsResponse": { "description": "Shared by 7 operations.", "type": "object", "properties": { "id": { "type": "string" }, "submissionType": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "totalPaye": { "type": "number" }, "totalUif": { "type": "number" }, "totalSdl": { "type": "number" }, "totalEti": { "type": "number" }, "totalPayable": { "type": "number" }, "totalDue": { "type": "number" }, "status": { "type": "string" }, "referenceNumber": { "type": "string" }, "paymentReferenceNumber": { "type": "string" }, "submittedAt": { "type": "string" }, "createdAt": { "type": "string" } } }, "PostApiSarsVatAdjustmentsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "kindLabel": { "type": "string" }, "field": { "type": "string" }, "date": { "type": "string", "format": "date" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "consideration": { "type": "number" }, "vatAmount": { "type": "number" }, "reason": { "type": "string" }, "documentRef": { "type": "string" }, "billId": { "type": "null" }, "assetId": { "type": "null" } } }, "PostApiSarsVatReviewActRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "finding": { "type": "string" }, "reason": { "type": "string" } } }, "PostApiTimeTrackingProjectsByIdTasksResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "chargeRate": { "type": "number" }, "costRate": { "type": "number" }, "active": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "effectiveRate": { "type": "number" }, "effectiveRateSource": { "type": "string" }, "loggedHours": { "type": "number" } } }, "PostApiTimeTrackingTimerStartResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "projectName": { "type": "string" }, "description": { "type": "string" }, "startedAtEpochMs": { "type": "integer" }, "billable": { "type": "boolean" } } }, "PostApiUsersByIdTransferOwnershipRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "roleId": { "type": "string" } } }, "PostApiWhatsappSendRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "to": { "type": "string", "format": "date" }, "templateName": { "type": "string" }, "templateParams": { "$ref": "#/components/schemas/PostApiWhatsappSendRequestTemplateParams" } } }, "PostApiWhatsappSendRequestTemplateParams": { "description": "Shared by 2 operations.", "type": "object", "properties": { "1": { "type": "string" } } }, "PostApiWhatsappSendResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "to": { "type": "string", "format": "date" }, "templateName": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" } } }, "PostApiWorkOrdersByIdIssueResponseLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "qty": { "type": "number" }, "actualUnitCost": { "type": "number" }, "actualTotalCost": { "type": "number" }, "standardUnitCost": { "type": "number" }, "short": { "type": "boolean" }, "issueType": { "type": "string" }, "issuedAt": { "type": "string" }, "journalId": { "type": "string" } } }, "PostApiWorkOrdersByIdReworkStepResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "workOrderId": { "type": "string" }, "woNumber": { "type": "string" }, "status": { "type": "string" }, "productName": { "type": "string" }, "routingId": { "type": "string" }, "routingName": { "type": "string" }, "expectedYieldPercent": { "type": "number" }, "qtyPlanned": { "type": "number" }, "qtyToStart": { "type": "number" }, "qtyCompleted": { "type": "number" }, "qtyScrapped": { "type": "number" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponseOperationsItem" } }, "operationCount": { "type": "integer" }, "completedOperationCount": { "type": "integer" }, "percentComplete": { "type": "number" }, "plannedHours": { "type": "number" }, "actualHours": { "type": "number" }, "varianceHours": { "type": "number" }, "actualLabourCost": { "type": "number" }, "currentOperation": { "type": "string" }, "holds": { "type": "array", "items": { "type": "object" } } } }, "PostApiWorkOrdersReworkResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "woNumber": { "type": "string" } } }, "PostApiWorkflowsBoardsRequestColumnsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "stage": { "type": "string" }, "wipLimit": { "type": "integer" }, "gate": { "type": "boolean" } } }, "PostApiWorkflowsBoardsResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "keyPrefix": { "type": "string" }, "description": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "timeProjectId": { "type": "string" }, "timeProjectName": { "type": "string" }, "archived": { "type": "boolean" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiWorkflowsBoardsResponseColumnsItem" } }, "itemCount": { "type": "integer" }, "openCount": { "type": "integer" }, "createdAt": { "type": "string" } } }, "PostApiWorkflowsBoardsResponseColumnsItem": { "description": "Shared by 5 operations.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "stage": { "type": "string" }, "position": { "type": "integer" }, "wipLimit": { "type": "integer" }, "count": { "type": "integer" } } }, "PostApiWorkflowsItemsByIdTimeResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "userName": { "type": "string" }, "minutes": { "type": "integer" }, "description": { "type": "string" }, "entryDate": { "type": "string", "format": "date" }, "billable": { "type": "boolean" }, "approved": { "type": "boolean" } } }, "PostApiWorkflowsItemsResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "boardId": { "type": "string" }, "columnId": { "type": "string" }, "stage": { "type": "string" }, "columnName": { "type": "string" }, "itemKey": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "itemType": { "type": "string" }, "priority": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "assigneeUserId": { "type": "string" }, "assigneeName": { "type": "string" }, "reporterUserId": { "type": "string" }, "reporterName": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "timeProjectId": { "type": "string" }, "timeProjectName": { "type": "string" }, "estimateMinutes": { "type": "integer" }, "loggedMinutes": { "type": "integer" }, "dueDate": { "type": "string", "format": "date" }, "rank": { "type": "number" }, "startedAt": { "type": "string" }, "closedAt": { "type": "string" }, "commentCount": { "type": "integer" }, "attachmentCount": { "type": "integer" }, "recurrenceId": { "type": "string" }, "recurrenceName": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PostApiWorkflowsRecurrencesResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "boardId": { "type": "string" }, "boardName": { "type": "string" }, "name": { "type": "string" }, "cadence": { "type": "string" }, "cadenceLabel": { "type": "string" }, "anchorDate": { "type": "string", "format": "date" }, "endsOn": { "type": "string", "format": "date" }, "active": { "type": "boolean" }, "columnId": { "type": "string" }, "columnName": { "type": "string" }, "lastRaisedOn": { "type": "string", "format": "date" }, "nextDueLabel": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiWorkflowsRecurrencesResponseLinesItem" } } } }, "PostApiWorkflowsRecurrencesResponseLinesItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "itemType": { "type": "string" }, "priority": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "assigneeUserId": { "type": "string" }, "assigneeName": { "type": "string" }, "estimateMinutes": { "type": "integer" }, "dueOffsetDays": { "type": "integer" }, "position": { "type": "integer" } } }, "PostAuthLogoutResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "message": { "type": "string" } } }, "PostDriverApiV1FuelRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "vehicleId": { "type": "string" }, "filledOn": { "type": "string", "format": "date" }, "litres": { "type": "number" }, "amount": { "type": "number" }, "odometerKm": { "type": "number" }, "garage": { "type": "string" }, "cardRef": { "type": "string" }, "tripId": { "type": "string" }, "clientReference": { "type": "string" } } }, "PostDriverApiV1FuelResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "tripId": { "type": "string" }, "filledOn": { "type": "string", "format": "date" }, "litres": { "type": "number" }, "amount": { "type": "number" }, "odometerKm": { "type": "number" }, "garage": { "type": "string" }, "cardRef": { "type": "string" }, "source": { "type": "string" }, "expenseId": { "type": "string" } } }, "PostDriverApiV1PositionsRequestPositionsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "accuracyM": { "type": "number" }, "speedKph": { "type": "number" }, "headingDeg": { "type": "number" }, "altitudeM": { "type": "number" }, "recordedAt": { "type": "string" }, "batteryPercent": { "type": "integer" }, "tripId": { "type": "string" } } }, "PostDriverApiV1StopsByIdProofRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "returnables": { "type": "array", "items": { "$ref": "#/components/schemas/PostDriverApiV1StopsByIdProofRequestReturnablesItem" } }, "temperatures": { "type": "array", "items": { "$ref": "#/components/schemas/PostDriverApiV1StopsByIdProofRequestTemperaturesItem" } }, "outcome": { "type": "string" }, "receivedByName": { "type": "string" }, "receivedByRole": { "type": "string" }, "receivedByIdNumber": { "type": "string" }, "signatureBase64": { "type": "string" }, "notes": { "type": "string" }, "capturedLatitude": { "type": "number" }, "capturedLongitude": { "type": "number" }, "capturedAccuracyM": { "type": "number" }, "capturedAt": { "type": "string" }, "deviceId": { "type": "string" }, "exceptionReasonCode": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostDriverApiV1StopsByIdProofRequestLinesItem" } }, "clientReference": { "type": "string" }, "collected": { "$ref": "#/components/schemas/PostDriverApiV1StopsByIdProofRequestCollected" } } }, "PostDriverApiV1StopsByIdProofRequestCollected": { "description": "Shared by 2 operations.", "type": "object", "properties": { "amount": { "type": "number" }, "method": { "type": "string" }, "reference": { "type": "string" } } }, "PostDriverApiV1StopsByIdProofRequestLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "stopLineId": { "type": "string" }, "qtyDelivered": { "type": "number" }, "qtyReturned": { "type": "number" }, "batchNumber": { "type": "string" }, "notes": { "type": "string" } } }, "PostDriverApiV1StopsByIdProofRequestReturnablesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "out": { "type": "integer" }, "back": { "type": "integer" } } }, "PostDriverApiV1StopsByIdProofRequestTemperaturesItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "celsius": { "type": "number" } } }, "PostDriverApiV1StopsByIdProofResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "ok": { "type": "boolean" }, "stop": { "$ref": "#/components/schemas/GetDriverApiV1TripsByIdResponseStopsItem" }, "tripStatus": { "type": "string" }, "serverTime": { "type": "string" }, "duplicateOfExistingProof": { "type": "boolean" }, "weaknesses": { "type": "array", "items": { "type": "string" } }, "strength": { "type": "string" } } }, "PostDriverApiV1TripsByIdMessagesReadResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "read": { "type": "string" } } }, "PostDriverApiV1TripsByIdMessagesRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "clientSeq": { "type": "integer" }, "writtenAt": { "type": "string" } } }, "PostDriverApiV1TripsByIdMessagesResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tripId": { "type": "string" }, "sender": { "type": "string" }, "senderName": { "type": "string" }, "body": { "type": "string" }, "photoUrl": { "type": "string" }, "clientSeq": { "type": "integer" }, "writtenAt": { "type": "string" }, "deliveredAt": { "type": "string" }, "readAt": { "type": "string" } } }, "PostDriverApiV1TripsByIdStartRequestInspectionAnswersItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "itemId": { "type": "string" }, "label": { "type": "string" }, "passed": { "type": "boolean" }, "note": { "type": "string" } } }, "PostSupplierApiV1CatalogueRequestPriceBreaksItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "minQty": { "type": "number" }, "unitPrice": { "type": "number" }, "note": { "type": "string" } } }, "PostSupplierApiV1InvoicesRequestLinesItem": { "description": "Shared by 13 operations.", "type": "object", "properties": { "description": { "type": "string" }, "poLineId": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "vatRate": { "type": "number" }, "vatInclusive": { "type": "boolean" }, "lineTotal": { "type": "number" }, "vatAmount": { "type": "number" } } }, "PostSupplierApiV1OffersResponse": { "description": "Shared by 10 operations.", "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" }, "order": { "$ref": "#/components/schemas/GetSupplierApiV1OrdersByIdResponse" }, "invoice": { "$ref": "#/components/schemas/GetSupplierApiV1InvoicesResponseItem" }, "rfq": { "$ref": "#/components/schemas/GetSupplierApiV1RfqsByIdResponse" } } }, "PutApiBomPlanningResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "sourceType": { "type": "string" }, "leadTimeDays": { "type": "integer" }, "safetyStock": { "type": "number" }, "lotSizing": { "type": "string" }, "fixedOrderQty": { "type": "number" }, "minOrderQty": { "type": "number" }, "orderMultiple": { "type": "number" }, "maxOrderQty": { "type": "number" }, "maxStockLevel": { "type": "number" }, "periodsOfSupply": { "type": "integer" }, "preferredSupplierId": { "type": "string" }, "preferredSupplierName": { "type": "string" }, "planningCost": { "type": "number" }, "abcClass": { "type": "string" }, "mrpActive": { "type": "boolean" }, "notes": { "type": "string" }, "lowLevelCode": { "type": "integer" }, "configured": { "type": "boolean" }, "onHand": { "type": "number" }, "hasBom": { "type": "boolean" } } }, "PutApiCompanyHierarchyByIdParentResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "parentCompanyId": { "type": "string" }, "name": { "type": "string" }, "tradeName": { "type": "string" }, "companyType": { "type": "string" }, "baseCurrency": { "type": "string" }, "isActive": { "type": "boolean" }, "depth": { "type": "integer" }, "path": { "type": "string" }, "childCount": { "type": "integer" }, "descendantCount": { "type": "integer" }, "ownershipPercent": { "type": "number" }, "effectiveOwnershipPercent": { "type": "number" }, "consolidationMethod": { "type": "string" }, "orphaned": { "type": "boolean" } } }, "PutApiDocumentSequencesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "docType": { "type": "string" }, "prefix": { "type": "string" }, "includeYear": { "type": "boolean" }, "nextNumber": { "type": "integer" }, "padLength": { "type": "integer" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "PutApiExpensesApprovalPolicyRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "secondApprovalFrom": { "type": "number" } } }, "PutApiExpensesCategoriesByIdRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer" }, "isActive": { "type": "boolean" }, "accountCode": { "type": "string" } } }, "PutApiInventoryPriceListsByIdPricesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "sellPrice": { "type": "number" }, "listPrice": { "type": "number" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiInventoryPriceListsByIdPricesResponseVariantsItem" } } } }, "PutApiInventoryPriceListsByIdPricesResponseVariantsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "variantId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "sellPrice": { "type": "number" }, "listPrice": { "type": "number" } } }, "PutApiInventoryReorderPointsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "locationId": { "type": "string" }, "reorderPoint": { "type": "number" }, "reorderQty": { "type": "number" } } }, "PutApiInvoiceSettingsCustomFieldsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiInvoiceSettingsCustomFieldsRequestFieldsItem" } } } }, "PutApiInvoiceSettingsCustomFieldsRequestFieldsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "docTypes": { "type": "array", "items": { "type": "string" } }, "onCustomerCopy": { "type": "boolean" } } }, "PutApiInvoiceSettingsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "numbering": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequestNumbering" }, "labels": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequestLabels" }, "show": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequestShow" }, "email": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequestEmail" }, "logos": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequestLogos" }, "defaults": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequestDefaults" }, "autoRecon": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequestAutoRecon" }, "activeTemplateName": { "type": "string" } } }, "PutApiInvoiceSettingsRequestAutoRecon": { "description": "Shared by 2 operations.", "type": "object", "properties": { "enabled": { "type": "boolean" }, "yoco": { "type": "boolean" }, "payfast": { "type": "boolean" }, "matchToleranceZar": { "type": "number" } } }, "PutApiInvoiceSettingsRequestDefaults": { "description": "Shared by 2 operations.", "type": "object", "properties": { "bankDetails": { "type": "string" }, "footer": { "type": "string" }, "terms": { "type": "string" }, "notes": { "type": "string" } } }, "PutApiInvoiceSettingsRequestEmail": { "description": "Shared by 2 operations.", "type": "object", "properties": { "replyTo": { "type": "string", "format": "date" }, "ccSelf": { "type": "boolean" }, "attachPdf": { "type": "boolean" }, "templates": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequestEmailTemplates" } } }, "PutApiInvoiceSettingsRequestEmailTemplates": { "description": "Shared by 2 operations.", "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequestEmailTemplatesInvoice" } } }, "PutApiInvoiceSettingsRequestEmailTemplatesInvoice": { "description": "Shared by 2 operations.", "type": "object", "properties": { "subject": { "type": "string" }, "body": { "type": "string" } } }, "PutApiInvoiceSettingsRequestLabels": { "description": "Shared by 2 operations.", "type": "object", "properties": { "docTitle": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequestLabelsDocTitle" }, "description": { "type": "string" }, "qty": { "type": "string" }, "unitPrice": { "type": "string" }, "rate": { "type": "string" }, "hours": { "type": "string" }, "discount": { "type": "string" }, "tax": { "type": "string" }, "net": { "type": "string" }, "total": { "type": "string" } } }, "PutApiInvoiceSettingsRequestLabelsDocTitle": { "description": "Shared by 2 operations.", "type": "object", "properties": { "invoice": { "type": "string" } } }, "PutApiInvoiceSettingsRequestLogos": { "description": "Shared by 2 operations.", "type": "object", "properties": { "primaryName": { "type": "string" }, "primaryDataUrl": { "type": "string" }, "primaryAttachmentId": { "type": "string" }, "associationName": { "type": "string" }, "associationDataUrl": { "type": "string" }, "associationAttachmentId": { "type": "string" } } }, "PutApiInvoiceSettingsRequestNumbering": { "description": "Shared by 2 operations.", "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequestNumberingInvoice" } } }, "PutApiInvoiceSettingsRequestNumberingInvoice": { "description": "Shared by 2 operations.", "type": "object", "properties": { "prefix": { "type": "string" }, "next": { "type": "integer" } } }, "PutApiInvoiceSettingsRequestShow": { "description": "Shared by 2 operations.", "type": "object", "properties": { "dueDate": { "type": "boolean" }, "contactName": { "type": "boolean" }, "businessAddress": { "type": "boolean" }, "vatNumber": { "type": "boolean" }, "discountColumn": { "type": "boolean" }, "paymentLinks": { "type": "boolean" }, "associationLogo": { "type": "boolean" } } }, "PutApiLedgerAccountBudgetsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "saved": { "type": "integer" } } }, "PutApiLedgerPeriodsByIdReviewResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "label": { "type": "string" }, "status": { "type": "string" }, "closedAt": { "type": "string" }, "reviewedAt": { "type": "string" }, "reviewedBy": { "type": "string" }, "closedByFirm": { "type": "boolean" } } }, "PutApiLogisticsDeliverySlotsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "slots": { "type": "array", "items": { "type": "string" } } } }, "PutApiLogisticsDriversByIdCostRateRequest": { "type": "object", "properties": { "costPerHour": { "type": "number" } } }, "PutApiLogisticsStopsByIdLocationResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "stopId": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "contactLocationSource": { "type": "string" } } }, "PutApiLogisticsStopsByIdRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "linkedCollectionStopId": { "type": "string" }, "stopType": { "type": "string" }, "contactId": { "type": "string" }, "documentId": { "type": "string" }, "jobCardId": { "type": "string" }, "stockLocationId": { "type": "string" }, "address": { "type": "string" }, "suburb": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "contactName": { "type": "string" }, "contactPhone": { "type": "string" }, "instructions": { "type": "string" }, "windowFrom": { "type": "string", "format": "date" }, "windowTo": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiLogisticsStopsByIdRequestLinesItem" } }, "clientId": { "type": "string" }, "hireContractId": { "type": "string" } } }, "PutApiLogisticsStopsByIdRequestLinesItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "invoiceLineId": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "qtyOrdered": { "type": "number" }, "uom": { "type": "string" }, "notes": { "type": "string" } } }, "PutApiMrpReplanSettingsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "firmPlannedOrders": { "type": "boolean" } } }, "PutApiPayrollSettingsRequestBanking": { "description": "Shared by 4 operations.", "type": "object", "properties": { "payingBankAccountId": { "type": "string" }, "acbUserCode": { "type": "string" }, "payingBranchCode": { "type": "string" } } }, "PutApiPayrollSettingsRequestDesignSectionsItem": { "description": "Shared by 4 operations.", "type": "object", "properties": { "section": { "type": "string" }, "visible": { "type": "boolean" } } }, "PutApiPayrollSettingsRequestLeave": { "description": "Shared by 4 operations.", "type": "object", "properties": { "annualDaysPerCycle": { "type": "number" }, "annualAccrualPerMonth": { "type": "number" }, "sickDaysPerCycle": { "type": "number" }, "familyDaysPerCycle": { "type": "number" }, "annualCarryOverDays": { "type": "number" } } }, "PutApiPayrollShiftRegisterResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "workDate": { "type": "string", "format": "date" }, "hours": { "type": "number" }, "category": { "type": "string" }, "allowanceTypeIds": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } } }, "PutApiPayrollTakeOnByEmployeeIdEtiMonthsRequestMonthsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "monthNumber": { "type": "integer" }, "cycle": { "type": "integer" }, "hours": { "type": "number" }, "remuneration": { "type": "number" }, "minimumWage": { "type": "number" }, "wagePaid": { "type": "number" }, "etiAmount": { "type": "number" } } }, "PutApiPayslipsByIdRequestEarningUnits": { "type": "object", "properties": { "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03": { "type": "number" } } }, "PutApiProcurementVendorsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "supplierSku": { "type": "string" }, "status": { "type": "string" }, "isPreferred": { "type": "boolean" }, "priority": { "type": "integer" }, "unitPrice": { "type": "number" }, "currency": { "type": "string" }, "leadTimeDays": { "type": "integer" }, "minOrderQty": { "type": "number" }, "orderMultiple": { "type": "number" }, "contractId": { "type": "string" }, "contractNumber": { "type": "string" }, "validFrom": { "type": "string", "format": "date" }, "validTo": { "type": "string", "format": "date" }, "onTimeReceipts": { "type": "integer" }, "lateReceipts": { "type": "integer" }, "onTimePercent": { "type": "number" }, "priceBreakCount": { "type": "integer" }, "unavailableReason": { "type": "string" }, "notes": { "type": "string" } } }, "PutApiReminderConfigsRequestStepsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "days": { "type": "integer" }, "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" } } }, "PutApiRentalRateCardsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "hireItemId": { "type": "string" }, "itemClass": { "type": "string" }, "day": { "type": "number" }, "week": { "type": "number" }, "fourWeek": { "type": "number" }, "weekend": { "type": "number" }, "minimumDays": { "type": "integer" } } }, "PutApiRentalSettingsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "chargeableDays": { "type": "string" } } }, "PutApiReportsAfsSettingsRequestPriorPeriodErrorsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "journalNumber": { "type": "string" }, "nature": { "type": "string" }, "occurredIn": { "type": "string" }, "profitAccountCode": { "type": "string" } } }, "PutApiReportsFavouritesRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "reportIds": { "type": "array", "items": { "type": "string" } } } }, "PutApiSarsItr14AssessedLossRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "yearEnd": { "type": "string", "format": "date" }, "amount": { "type": "number" } } }, "PutApiSarsVatBasisRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "basis": { "type": "string" }, "effectiveFrom": { "type": "string", "format": "date" } } }, "PutApiSecurityPolicyRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "sessionTimeoutMins": { "type": "integer" }, "passwordMinLength": { "type": "integer" }, "passwordRequireUpper": { "type": "boolean" }, "passwordRequireDigit": { "type": "boolean" }, "passwordRequireSpecial": { "type": "boolean" }, "lockoutMaxAttempts": { "type": "integer" }, "lockoutWindowMins": { "type": "integer" }, "require2faForAdmins": { "type": "boolean" }, "require2faForEveryone": { "type": "boolean" }, "retentionDays": { "type": "integer" }, "retentionFloorDays": { "type": "integer" }, "retentionNote": { "type": "null" }, "maxDevicesPerUser": { "type": "integer" } } }, "PutApiTenantSettingsRequestBranding": { "description": "Shared by 2 operations.", "type": "object", "properties": { "brandColorHex": { "type": "string" } } }, "PutApiTenantSettingsRequestDataPrefs": { "description": "Shared by 2 operations.", "type": "object", "properties": { "autoBackupEnabled": { "type": "boolean" }, "autoBackupFrequency": { "type": "string" }, "retentionMonths": { "type": "integer" } } }, "PutApiTenantSettingsRequestLocalisation": { "description": "Shared by 2 operations.", "type": "object", "properties": { "currency": { "type": "string" }, "dateFormat": { "type": "string" }, "numberFormat": { "type": "string" } } }, "PutApiTimeTrackingSettingsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "lockDate": { "type": "string", "format": "date" }, "weeklyHours": { "type": "number" } } }, "PutApiWorkflowsChecklistByIdResponseItem": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" }, "doneAt": { "type": "string" }, "doneByName": { "type": "string" } } } }, "examples": { "DeleteApiWorkflowsCommentsByIdResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "itemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "authorUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "authorName": "Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached.", "createdAt": "2026-09-01T09:15:00Z" } }, "GetApiAccountsResponseExample": { "description": "Shared by 2 operations.", "value": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "parentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "accountType": "asset", "accountSubtype": "text", "currency": "ZAR", "isActive": true, "isSystem": false, "normalBalance": "text", "children": [ null ] } ] }, "GetApiBillsByIdPaymentsResponseExample": { "description": "Shared by 2 operations.", "value": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "amount": 10005.0, "currency": "ZAR", "method": "eft", "reference": "INV-0001", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "remaining": 1.0 } ] }, "GetApiBomByBomIdAttachmentsResponseExample": { "description": "Shared by 10 operations.", "value": { "attachments": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "filename": "SignedPO-4417.pdf", "caption": "Serial plate before fitting", "contentType": "application/pdf", "sizeBytes": 1, "url": "https://app.ledgrsa.com/pay/3f1a7c92", "uploadedByName": "Karoo Fresh Holdings Ltd", "createdAt": "2026-09-01T09:15:00Z" } ] } }, "GetApiBomLinesByLineIdAlternatesResponseExample": { "description": "Shared by 2 operations.", "value": { "alternates": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "alternateProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "qtyPer": 1.0, "priority": 1, "notes": "Budget deferred to the next financial year.", "available": 1.0 } ] } }, "GetApiBomPlanningBufferSuggestionResponseExample": { "description": "Shared by 2 operations.", "value": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Wall bracket 300mm", "sku": "KSW-RM-BRKT300", "qtyPrecision": 0, "abcClass": "A", "leadTimeDays": 61, "currentSafetyStock": 0.0, "currentReorderPoint": null, "historyMonths": 8, "blocker": null, "serviceLevel": 95, "monthlyMean": 10.0, "monthlySwing": 2.13809, "leadTimeDemand": 20.04, "safetyStock": 5.0, "reorderPoint": 26.0 } ] }, "GetApiContactsByContactIdTransactionsResponseExample": { "description": "Shared by 2 operations.", "value": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "occurredAt": "2026-09-01T09:15:00Z", "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "amount": 10005.0, "currency": "ZAR", "vatRate": 15.0, "externalRef": "INV-0001", "metadata": "text", "status": "sent", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoicedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z" } ] }, "GetApiContactsByIdConsentResponseExample": { "description": "Shared by 2 operations.", "value": { "contactId": "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e", "channels": [ { "channel": "email", "label": "Email", "mayMarket": true, "latest": { "id": "7b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "channel": "email", "channelLabel": "Email", "status": "given", "statusLabel": "Consent given", "method": "online_form", "methodLabel": "Online form", "note": "Ticked the newsletter box on the quote acceptance page.", "recordedBy": "Thandi Mokoena", "recordedAt": "2026-09-26T10:15:00Z" } }, { "channel": "whatsapp", "label": "WhatsApp", "mayMarket": false }, { "channel": "sms", "label": "SMS", "mayMarket": false }, { "channel": "phone", "label": "Phone call", "mayMarket": false } ], "history": [ { "id": "7b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "channel": "email", "channelLabel": "Email", "status": "given", "statusLabel": "Consent given", "method": "online_form", "methodLabel": "Online form", "note": "Ticked the newsletter box on the quote acceptance page.", "recordedBy": "Thandi Mokoena", "recordedAt": "2026-09-26T10:15:00Z" } ], "notMarketing": "Invoices, statements, payment reminders, quotes and payslips are not marketing and are sent whatever is recorded here." } }, "GetApiContactsByIdPriceListResponseExample": { "description": "Shared by 2 operations.", "value": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "priceList": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "prices": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "unitPrice": 2900.0 } ] } } }, "GetApiContactsByIdResponseExample": { "description": "Shared by 4 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactType": "customer", "name": "Karoo Fresh Holdings Ltd", "tradingName": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "mobile": "+27 82 555 0143", "vatNumber": "4123456789", "registrationNo": "2021/123456/07", "creditLimit": 1.0, "creditUsed": 1.0, "addressLine1": "12 Long Street", "addressLine2": "Woodstock", "city": "Cape Town", "province": "Western Cape", "postalCode": "CT-001", "country": "South Africa", "postalAddressLine1": "12 Long Street", "postalAddressLine2": "Woodstock", "postalCity": "Cape Town", "postalProvince": "Western Cape", "postalPostalCode": "CT-001", "postalCountry": "South Africa", "currency": "ZAR", "paymentTerms": 1, "notes": "Budget deferred to the next financial year.", "isActive": true, "tags": [ "text" ], "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "GetApiContactsInformationOfficerResponseExample": { "description": "Shared by 2 operations.", "value": { "companyId": "8b5d2f1e-3c4a-4e9b-a7d6-1f2e3c4b5a69", "recorded": true, "name": "Naledi Dlamini", "email": "privacy@karoofresh.example", "phone": "0215550101", "regulatorRegistration": "IRR/2026/0042", "statement": "Questions about personal information go to the information officer, Naledi Dlamini (privacy@karoofresh.example, 0215550101)." } }, "GetApiDocumentsOcrResponseExample": { "description": "Shared by 2 operations.", "value": { "ok": true, "engine": "text", "documentKind": "invoice", "extraction": { "supplierName": "Karoo Fresh Holdings Ltd", "supplierVatNumber": "4123456789", "documentNumber": "INV-0001", "documentDate": "2026-09-01", "subtotal": 8700.0, "vatAmount": 1305.0, "vatRatePercent": 15.0, "total": 10005.0, "currency": "ZAR", "categoryHint": "text", "litres": 1.0, "lineItems": [ { "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "amount": 10005.0, "confidence": 1 } ], "fields": [ { "name": "Karoo Fresh Holdings Ltd", "confidence": 1, "source": "referral", "evidence": "text" } ], "reconciliation": { "subtotalPlusVatMatchesTotal": true, "impliedVatRatePercent": 15.0, "vatRateRecognised": true, "discrepancy": 1.0, "lineItemsSum": 1.0, "lineItemsMatchSubtotal": true }, "overallConfidence": 1, "engineConfidence": 1, "engineScored": false, "warnings": [], "droppedLowConfidence": [ "text" ], "manualEntryRequired": true }, "rawText": "text", "ocrResultId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "failure": "text", "error": "text", "manualEntryRequired": false, "variant": "text", "passes": 1, "pageCount": 1, "pagesRead": 1, "truncated": false, "exactText": false, "duplicateOf": { "ocrResultId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "scannedAt": "2026-09-01T09:15:00Z", "expenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "message": "Saved." }, "suggestion": { "category": "Office supplies", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reason": "Budget deferred to the next financial year." } } }, "GetApiEmployeesByIdEquityResponseExample": { "description": "Shared by 2 operations.", "value": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "race": "text", "gender": "text", "disabled": false, "foreignNational": false, "occupationalLevel": "text", "updatedAt": "2026-09-01T09:15:00Z" } }, "GetApiEmployeesByIdPayslipsResponseExample": { "description": "Shared by 2 operations.", "value": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "periodId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "payDate": "2026-09-01", "basicSalary": 1.0, "travelAllowance": 1.0, "overtime": 1.0, "commission": 1.0, "bonus": 1.0, "otherAllowances": 1.0, "grossSalary": 1.0, "pensionContribution": 1.0, "medicalAidContribution": 1.0, "employerRetirement": 1.0, "employerMedical": 1.0, "thirdPartyDeductions": 1.0, "taxableRemuneration": 1305.0, "travelInclusionRate": 15.0, "payeTax": 1305.0, "uifEmployee": 1.0, "uifEmployer": 1.0, "sdl": 1.0, "netPay": 8700.0, "ytdGross": 1.0, "ytdPaye": 1.0, "hoursWorked": 3.0, "etiHoursSource": "referral", "etiAmount": 10005.0, "etiReason": "Budget deferred to the next financial year.", "catchUpPaye": 1.0, "catchUpNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "deductionLines": [ { "beneficiaryName": "Karoo Fresh Holdings Ltd", "reference": "INV-0001", "employeeAmount": 10005.0, "employerAmount": 10005.0 } ], "fringeBenefitsOtherRemuneration": 1.0, "status": "sent", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] }, "GetApiExpensesByIdResponseExample": { "description": "Shared by 6 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "vendor": "Karoo Fresh Holdings Ltd", "supplierVatNumber": "4123456789", "category": "Office supplies", "amount": 10005.0, "vatAmount": 1305.0, "vatRate": 15.0, "currency": "ZAR", "status": "sent", "receiptUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "notes": "Budget deferred to the next financial year.", "rejectionReason": "Budget deferred to the next financial year.", "createdBy": "Thandi Mokoena", "createdByName": "Thandi Mokoena", "approvedBy": "Thandi Mokoena", "approvedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectName": "Karoo Fresh Holdings Ltd", "rechargeable": false, "rechargeInvoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } }, "GetApiFixedAssetsDeferredTaxResponseExample": { "description": "Shared by 2 operations.", "value": { "yearEnd": "2026-09-30", "carryingAmount": 10005.0, "taxValue": 1305.0, "temporaryDifference": 1.0, "ratePercent": 15.0, "requiredBalance": 10005.0, "bookedBalance": 10005.0, "movement": 1.0, "unmappedAssets": [ "text" ], "declinedReason": "Budget deferred to the next financial year." } }, "GetApiFxRatesResponseExample": { "description": "Shared by 2 operations.", "value": { "baseCurrency": "ZAR", "rates": [ { "fromCurrency": "ZAR", "toCurrency": "ZAR", "rate": 15.0, "asOf": "text", "source": "referral", "fetchedAt": "2026-09-01T09:15:00Z", "stale": false } ], "anyStale": false, "summary": "Consulting services — August 2026" } }, "GetApiGiftVouchersByIdResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "GV-7F3A9C21", "faceValue": 500.0, "balance": 350.0, "status": "active", "issuedOn": "2026-10-01", "expiresOn": "2029-10-01", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "movements": [ { "kind": "issued", "amount": 500.0, "on": "2026-10-01" }, { "kind": "redeemed", "amount": 150.0, "on": "2026-10-14", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0042" } ] } }, "GetApiIntercompanyTransactionsByIdResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "transactionDate": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "currency": "ZAR", "exchangeRate": 1.0, "accountIdFrom": "2026-09-01", "accountIdTo": "2026-09-30", "status": "PENDING", "settledOn": "2026-09-01", "settledAt": "2026-09-01T09:15:00Z", "settledByName": "Karoo Fresh Holdings Ltd", "settlementReference": "INV-0001", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "GetApiInventoryBatchesByIdRecallResponseExample": { "description": "Shared by 2 operations.", "value": { "direction": "forward", "rootBatchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rootBatchNumber": "INV-0001", "rootProductName": "Karoo Fresh Holdings Ltd", "rootSku": "LEN-TP-14G4", "nodes": [ { "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "batchNumber": "INV-0001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "qty": 3.0, "unitCost": 2900.0, "supplier": "Karoo Fresh Holdings Ltd", "expiryDate": "2026-09-01", "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "workOrderStatus": "sent", "consumedAt": "2026-09-01T09:15:00Z", "depth": 1, "kind": "standard" } ], "maxDepth": 1, "truncated": false, "unaccountedQty": 3.0, "receivers": [ { "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "batchNumber": "INV-0001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "qty": 3.0, "sourceType": "invoice", "sourceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "date": "2026-09-01", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143" } ], "receivedQty": 3.0, "onHandQty": 3.0, "quarantined": false } }, "GetApiInventoryBomsResponseExample": { "description": "Shared by 2 operations.", "value": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "version": "1", "outputQty": 3.0, "labourCost": 10005.0, "overheadCost": 10005.0, "status": "sent", "notes": "Budget deferred to the next financial year.", "lineCount": 3, "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentVariantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentName": "Karoo Fresh Holdings Ltd", "componentSku": "LEN-TP-14G4", "qtyPer": 1.0, "scrapPercent": 15.0, "notes": "Budget deferred to the next financial year.", "sortOrder": 1 } ], "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "createdAt": "2026-09-01T09:15:00Z", "submittedAt": "2026-09-01T09:15:00Z", "submittedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "approvedByName": "Thandi Mokoena", "decisionNote": "Budget deferred to the next financial year.", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena" } ] }, "GetApiInventoryBuildsByIdResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomName": "Karoo Fresh Holdings Ltd", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyBuilt": 1.0, "status": "sent", "componentCost": 10005.0, "labourCost": 10005.0, "overheadCost": 10005.0, "totalCost": 10005.0, "unitCost": 2900.0, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "builtAt": "2026-09-01T09:15:00Z", "lines": [ { "componentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentName": "Karoo Fresh Holdings Ltd", "qtyRequired": 1.0, "qtyConsumed": 1.0, "unitCost": 2900.0, "totalCost": 10005.0, "short": false } ] } }, "GetApiInventoryCycleCountsResponseExample": { "description": "Shared by 2 operations.", "value": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "cadence": "text", "scope": "text", "abcClass": "text", "binId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "binCode": "CT-001", "active": true, "lastPeriod": "2026-09" } ] }, "GetApiInventorySerialsByIdResponseExample": { "description": "Shared by 2 operations.", "value": { "serial": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "serialNumber": "INV-0001", "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplier": "Karoo Fresh Holdings Ltd", "receivedDate": "2026-09-01", "unitCost": 2900.0, "status": "sent", "soldDate": "2026-09-01", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "autoAssigned": false, "warrantyExpiry": "2026-09-30", "warrantyDaysRemaining": 30, "underWarranty": false, "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z" }, "events": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "event": "text", "fromStatus": "sent", "toStatus": "sent", "occurredAt": "2026-09-01T09:15:00Z", "reference": "INV-0001", "notes": "Budget deferred to the next financial year." } ] } }, "GetApiInventorySerialsResponseExample": { "description": "Shared by 2 operations.", "value": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "serialNumber": "INV-0001", "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplier": "Karoo Fresh Holdings Ltd", "receivedDate": "2026-09-01", "unitCost": 2900.0, "status": "sent", "soldDate": "2026-09-01", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "autoAssigned": false, "warrantyExpiry": "2026-09-30", "warrantyDaysRemaining": 30, "underWarranty": false, "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z" } ] }, "GetApiInvoiceSettingsResponseExample": { "description": "Shared by 2 operations.", "value": { "numbering": { "invoice": { "prefix": "INV-", "next": 1 } }, "labels": { "docTitle": { "invoice": "Tax Invoice" }, "description": "Consulting services — August 2026", "qty": "text", "unitPrice": "text", "rate": "text", "hours": "text", "discount": "text", "tax": "text", "net": "text", "total": "text" }, "show": { "dueDate": true, "contactName": true, "businessAddress": true, "vatNumber": true, "discountColumn": true, "paymentLinks": true, "associationLogo": true }, "email": { "replyTo": "2026-09-30", "ccSelf": true, "attachPdf": true, "templates": { "invoice": { "subject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached." } } }, "logos": { "primaryName": "Karoo Fresh Holdings Ltd", "primaryDataUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "primaryAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "associationName": "Karoo Fresh Holdings Ltd", "associationDataUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "associationAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, "defaults": { "bankDetails": "FNB Business Account 62012345678, branch 250655", "footer": "Thank you for your business.", "terms": "Goods remain the property of the seller until paid in full.", "notes": "Budget deferred to the next financial year." }, "autoRecon": { "enabled": true, "yoco": true, "payfast": true, "matchToleranceZar": 1.0 }, "activeTemplateName": "Karoo Fresh Holdings Ltd" } }, "GetApiInvoicesByIdAttachmentsResponseExample": { "description": "Shared by 3 operations.", "value": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "filename": "SignedPO-4417.pdf", "caption": "Serial plate before fitting", "contentType": "application/pdf", "sizeBytes": 1, "sequence": 1, "uploadedByName": "Karoo Fresh Holdings Ltd", "createdAt": "2026-09-01T09:15:00Z", "sendWithDocument": false } ] }, "GetApiInvoicesByIdInstalmentCreditResponseExample": { "description": "Shared by 6 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "status": "sent", "deliveredOn": "2026-09-01", "cashPrice": 10005.0, "vatInCashPrice": 1305.0, "deposit": 1.0, "principalDebt": 1.0, "termMonths": 1, "annualRatePercent": 15.0, "referenceRatePercent": 15.0, "creditTypeLabel": "Karoo Fresh Holdings Ltd", "maximumRatePercent": 15.0, "initiationFee": 1.0, "monthlyServiceFee": 1.0, "instalment": 1.0, "costOfCredit": 10005.0, "totalPayable": 10005.0, "principalOutstanding": 1.0, "chargesOutstanding": 1.0, "balance": 10005.0, "paidToDate": 1.0, "nextDueOn": "2026-09-01", "nextInstalment": 1.0, "schedule": [ { "number": 1, "dueOn": "2026-09-01", "instalment": 1.0, "interest": 1.0, "fees": 1.0, "capital": 1.0, "balanceAfter": 10005.0, "charged": false, "chargeNumber": "INV-0001" } ], "statement": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "on": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "balanceAfter": 10005.0, "documentNumber": "INV-0001" } ] } }, "GetApiInvoicesByIdLaybyResponseExample": { "description": "Shared by 4 operations.", "value": { "laybyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "INV-0001", "status": "sent", "total": 10005.0, "held": 1.0, "stillOwed": 1.0, "feePercent": 15.0, "feeIfCancelledNow": 1.0, "refundIfCancelledNow": 1.0, "movements": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "amount": 10005.0, "on": "2026-09-01", "method": "eft", "reference": "INV-0001", "invoiceNumber": "INV-0001" } ], "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001" } }, "GetApiInvoicesByIdResponseExample": { "description": "Shared by 5 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "documentType": "invoice", "invoiceNumber": "INV-0001", "status": "sent", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "currency": "ZAR", "exchangeRate": 1.0, "subtotal": 8700.0, "discountTotal": 0.0, "vatTotal": 1305.0, "total": 10005.0, "amountPaid": 0.0, "amountDue": 10005.0, "vatRegistered": true, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "terms": "30", "sourceDocumentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena", "declineReason": "Budget deferred to the next financial year.", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "discountRate": 0.0, "vatRate": 15.0, "vatInclusive": false, "lineSubtotal": 8700.0, "discountAmount": 0.0, "vatAmount": 1305.0, "lineTotal": 10005.0, "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "discountType": "PERCENT", "discountFixed": 0.0, "kind": "PRODUCT", "productCode": "CT-001", "warehouseBin": "A-12-03" } ], "payments": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "amount": 10005.0, "method": "eft", "reference": "INV-0001", "createdAt": "2026-09-01T09:15:00Z" } ], "reminders": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sentDate": "2026-09-01", "channel": "email", "createdAt": "2026-09-01T09:15:00Z" } ], "contactRemindersPaused": false, "tcs": "Goods remain the property of the seller until paid in full.", "bankDetails": "FNB Business Account 62012345678, branch 250655", "footer": "Thank you for your business.", "deposit": { "percent": 15.0, "amount": 10005.0, "appliedTo": "2026-09-30" }, "picking": { "warehouse": "Cape Town HQ", "picker": "Thandi Mokoena", "lines": [ { "idx": 1, "picked": true } ] }, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "GetApiLandedCostsDefaultsResponseExample": { "description": "Shared by 2 operations.", "value": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productSku": "LEN-TP-14G4", "chargeType": "standard", "label": "Karoo Fresh Holdings Ltd", "percentOfValue": 15.0, "capitalise": true, "active": true, "notes": "Budget deferred to the next financial year.", "specificity": 3 } ] }, "GetApiLedgerJournalsByIdAttachmentsResponseExample": { "description": "Shared by 2 operations.", "value": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "7c2e9b14-0d3a-4f6e-8b21-5a9c1d7e3f40", "filename": "working-paper.pdf", "contentType": "application/pdf", "sizeBytes": 20480 } ] }, "GetApiLogisticsStopsByIdCustomerResponseExample": { "description": "Shared by 2 operations.", "value": { "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "trackPath": "text", "podPath": "text", "linkValidDays": 30, "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "contactEmail": "accounts@karoofresh.example", "contactPhone": "+27 82 555 0143", "updatesOptedOut": false, "notices": [ { "event": "dispatched", "channel": "email", "status": "queued", "recipient": "text", "detail": "Saved.", "at": "2026-09-01T09:15:00Z" } ], "rating": 1, "ratingComment": "Budget deferred to the next financial year.", "ratedAt": "2026-09-01T09:15:00Z" } }, "GetApiLogisticsStopsByIdResponseExample": { "description": "Shared by 4 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "sequence": 1, "stopType": "delivery", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactDisplayName": "Karoo Fresh Holdings Ltd", "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "documentType": "invoice", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobCardNumber": "JC-0001", "stockLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "address": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "latitude": 1.0, "longitude": 1.0, "contactName": "Karoo Fresh Holdings Ltd", "contactPhone": "+27 82 555 0143", "instructions": "Budget deferred to the next financial year.", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "status": "sent", "enRouteAt": "2026-09-01T09:15:00Z", "arrivedAt": "2026-09-01T09:15:00Z", "departedAt": "2026-09-01T09:15:00Z", "arrivalLatitude": 1.0, "arrivalLongitude": 1.0, "arrivalAccuracyM": 1.0, "arrivalDistanceM": 1.0, "exceptionReasonCode": "CT-001", "exceptionReasonLabel": "Karoo Fresh Holdings Ltd", "exceptionNotes": "Budget deferred to the next financial year.", "stockPostedAt": "2026-09-01T09:15:00Z", "stockWarnings": [ "text" ], "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyOrdered": 1.0, "qtyDelivered": 1.0, "qtyReturned": 1.0, "uom": "each", "batchNumber": "INV-0001", "stockMovementId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "shortfall": 1.0, "qtyLoaded": 1.0, "loadCheckedAt": "2026-09-01T09:15:00Z", "service": false } ], "proof": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "outcome": "delivered", "receivedByName": "Karoo Fresh Holdings Ltd", "receivedByRole": "Accountant", "signatureAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "capturedLatitude": 1.0, "capturedLongitude": 1.0, "capturedAccuracyM": 1.0, "distanceFromStopM": 1.0, "capturedAt": "2026-09-01T09:15:00Z", "recordedAt": "2026-09-01T09:15:00Z", "clockSkewMinutes": 1, "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "deviceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "exceptionReasonCode": "CT-001", "exceptionReasonLabel": "Karoo Fresh Holdings Ltd", "photos": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "caption": "Serial plate before fitting", "sequence": 1 } ], "capturedInOffice": false, "learnableLocation": false, "strength": "STRONG", "evidenceStatement": "text", "weaknesses": [ "text" ] }, "collectable": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "amountDue": 10005.0, "foreignCurrency": "ZAR" }, "collection": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "paymentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 10005.0, "method": "cash", "reference": "INV-0001", "collectedAt": "2026-09-01T09:15:00Z", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "bankedAt": "2026-09-01T09:15:00Z", "bankingId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } }, "GetApiLogisticsTripsByIdCostResponseExample": { "description": "Shared by 3 operations.", "value": { "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "tripDate": "2026-09-01", "status": "sent", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "distanceKm": 1.0, "drops": 1, "driverHours": 3.0, "fuel": 1.0, "other": 1.0, "labour": 1.0, "standing": 1.0, "total": 10005.0, "perKm": 1.0, "perDrop": 1.0, "revenue": 1.0, "margin": 1.0, "marginPercent": 15.0, "gaps": [ "text" ], "lines": [ { "kind": "fuel", "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0 } ], "stops": [ { "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sequence": 1, "name": "Karoo Fresh Holdings Ltd", "status": "sent", "charge": 1.0 } ] } }, "GetApiMrpBatchTraceResponseExample": { "description": "Shared by 2 operations.", "value": { "direction": "text", "rootBatchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rootBatchNumber": "INV-0001", "rootProductName": "Karoo Fresh Holdings Ltd", "rootSku": "LEN-TP-14G4", "nodes": [ { "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "batchNumber": "INV-0001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "qty": 3.0, "unitCost": 2900.0, "supplier": "Karoo Fresh Holdings Ltd", "expiryDate": "2026-09-01", "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "workOrderStatus": "sent", "consumedAt": "2026-09-01T09:15:00Z", "depth": 1, "kind": "standard" } ], "maxDepth": 1, "truncated": false, "unaccountedQty": 3.0 } }, "GetApiMrpScrapReasonsResponseExample": { "description": "Shared by 2 operations.", "value": [ { "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "controllable": true, "active": true, "isCustom": false, "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] }, "GetApiMrpSupplyRulesResponseExample": { "description": "Shared by 2 operations.", "value": [ { "id": "5d8e2a17-3c94-4b0f-8e61-a27f9c4d1b58", "locationId": "8c2d4e61-0a7b-4f39-b5d2-91e6c3a8f7b4", "locationName": "Durban branch", "sourceLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceLocationName": "Johannesburg factory", "leadDays": 3 } ] }, "GetApiPayrollDocumentExpiriesResponseExample": { "description": "Shared by 5 operations.", "value": { "documents": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "kind": "invoice", "kindLabel": "Karoo Fresh Holdings Ltd", "title": "Karoo Fresh Holdings Ltd", "notes": "Budget deferred to the next financial year.", "issuedOn": "2026-09-01", "expiresOn": "2026-09-01", "expiryStatus": "NO_DATE", "expirySentence": "text", "daysUntilExpiry": 30, "needsAttention": true, "source": "referral", "verifiedAt": "2026-09-01T09:15:00Z", "verifiedByName": "Karoo Fresh Holdings Ltd", "fileUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "contentType": "application/pdf", "sizeBytes": 1, "createdAt": "2026-09-01T09:15:00Z" } ], "kinds": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "consequence": "text", "expires": true, "employeeMayUpload": true } ], "expiredCount": 3, "expiringSoonCount": 3, "attentionSummary": "Consulting services — August 2026", "warnDays": 30 } }, "GetApiPayrollEmp501ResponseExample": { "description": "Shared by 2 operations.", "value": { "taxYear": "2027", "months": [ { "month": "2026-09", "paye": 1.0, "uif": 1.0, "sdl": 1.0, "eti": 1.0, "total": 10005.0, "paid": 1.0 } ], "interimPaye": 1.0, "interimUif": 1.0, "interimSdl": 1.0, "interimEti": 1.0, "interimTotal": 10005.0, "interimPaid": 1.0, "annualPaye": 1.0, "annualUif": 1.0, "annualSdl": 1.0, "annualEti": 1.0, "annualTotal": 10005.0, "annualPaid": 1.0 } }, "GetApiPayrollEmployeesByEmployeeIdEarningsResponseExample": { "description": "Shared by 3 operations.", "value": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "basicSalary": 1.0, "earnings": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "sarsCode": "CT-001", "sarsLabel": "Karoo Fresh Holdings Ltd", "calculation": "text", "unitLabel": "Karoo Fresh Holdings Ltd", "amount": 10005.0, "percent": 15.0, "rate": 15.0, "units": 1.0, "usingDefault": true, "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "taxable": true, "preview": 1.0, "working": "text" } ], "available": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "sarsCode": "CT-001", "sarsLabel": "Karoo Fresh Holdings Ltd", "calculation": "text", "calculationLabel": "Karoo Fresh Holdings Ltd", "defaultAmount": 10005.0, "defaultPercent": 15.0, "defaultRate": 15.0, "unitLabel": "Karoo Fresh Holdings Ltd", "active": true, "sortOrder": 1, "notes": "Budget deferred to the next financial year.", "taxable": true, "assignedCount": 3, "glAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "postsToLabel": "Karoo Fresh Holdings Ltd", "postsToIsDefault": true, "problem": "text" } ] } }, "GetApiPayrollEmployeesByIdPortalLinkResponseExample": { "description": "Shared by 2 operations.", "value": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "active": true, "issuedAt": "2026-09-01T09:15:00Z", "expiresAt": "2026-09-01T09:15:00Z", "revokedAt": "2026-09-01T09:15:00Z", "lastAccessedAt": "2026-09-01T09:15:00Z", "accessCount": 3 } }, "GetApiPayrollEtiResponseExample": { "description": "Shared by 3 operations.", "value": { "monthStart": "2026-09-01", "monthEnd": "2026-09-30", "monthLabel": "Karoo Fresh Holdings Ltd", "bandTable": "text", "employees": [ { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "employeeName": "Thandi Mokoena", "dateOfBirth": "1988-04-12", "startDate": "2026-09-01", "ageAtMonthEnd": 1, "qualifies": false, "qualifyingMonth": 9, "monthsUsed": 1, "firstYear": false, "amount": 10005.0, "reason": "Budget deferred to the next financial year.", "qualifiesButUnclaimed": false, "remuneration": 1.0, "basis": "invoice", "minimumWageMonthly": 1.0, "noWageRegulatingMeasure": false, "monthsClaimedBeforeLedgr": 1, "exclusion": "text", "ordinaryHoursMonthly": 3.0, "staleVsCapturedFacts": "text", "hoursWorked": 3.0, "hoursSource": "referral", "sezCode": "COE" } ], "qualifyingCount": 3, "calculatedTotal": 10005.0, "unclaimedCount": 3, "recomputeCount": 3, "claim": { "monthEnd": "2026-09-30", "broughtForward": 1.0, "calculated": 1.0, "available": 1.0, "utilised": 1.0, "grossPaye": 1.0, "netPaye": 8700.0, "carriedForward": 1.0, "ringFencedForRefund": 1.0 }, "estimated": true, "employer": { "sezQualifyingCompany": false, "ineligibleEmployer": "pfma_public_entity", "ineligibleReason": "This employer may not claim the Employment Tax Incentive: it is a public entity listed in Schedule 2 or 3 to the Public Finance Management Act (ETI Act s3(b)(ii))." } } }, "GetApiPayrollPeriodsByIdEmp201ResponseExample": { "description": "Shared by 2 operations.", "value": { "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "totalPaye": 12400.0, "totalUif": 1062.72, "totalSdl": 890.0, "totalEti": 500.0, "totalEtiCalculated": 10005.0, "payeAfterEti": 1.0, "totalPayable": 13852.72, "employeeCount": 3, "lines": [ { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "paye": 1.0, "uif": 1.0, "sdl": 1.0 } ] } }, "GetApiPayrollSettingsResponseExample": { "description": "Shared by 4 operations.", "value": { "design": { "title": "Karoo Fresh Holdings Ltd", "accentHex": "#0D47A1", "showLogo": true, "logoAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "logoScalePercent": 100, "sections": [ { "section": "EMPLOYER", "visible": true } ], "labels": { "key": "text" }, "bankAccount": "masked", "density": "compact", "showTaxNumber": true, "showIdNumber": false, "message": "Saved.", "footerText": "text", "presetId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, "leave": { "annualDaysPerCycle": 1.0, "annualAccrualPerMonth": 1.0, "sickDaysPerCycle": 1.0, "familyDaysPerCycle": 1.0, "annualCarryOverDays": 1.0 }, "logoUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "logoInheritedFromInvoices": false, "presets": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "forWhom": "text" } ], "sections": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "required": true, "bceaReference": "INV-0001" } ], "leaveCarryOverNote": "Budget deferred to the next financial year.", "leaveIsStatutoryMinimum": true, "banking": { "payingBankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "acbUserCode": "AB12", "payingBranchCode": "632005" }, "payingBankAccountOptions": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "accountMasked": "text", "bankName": "FNB" } ] } }, "GetApiPayrollTakeOnByEmployeeIdEtiMonthsResponseExample": { "description": "Shared by 2 operations.", "value": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "taxYearEndYear": 2027, "months": [ { "monthNumber": 3, "cycle": 1, "hours": 160.0, "remuneration": 4500.0, "minimumWage": 2500.0, "wagePaid": 4500.0, "etiAmount": 1125.0 } ] } }, "GetApiPayrollTakeOnResponseExample": { "description": "Shared by 2 operations.", "value": { "taxYearEndYear": 2026, "taxYear": "2027", "midYearSwitch": false, "firstLedgrPayDate": "2026-09-01", "employees": [ { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "employeeName": "Thandi Mokoena", "startDate": "2026-09-01", "stated": false, "taxYearEndYear": 2026, "taxYear": "2027", "figures": { "taxYearEndYear": 2026, "periodsWorked": 1, "remuneration": 1.0, "paye": 1.0, "annualPayments": 1.0, "payeOnAnnualPayments": 1.0, "uifEmployee": 1.0, "uifEmployer": 1.0, "sdl": 1.0, "retirementEmployee": 1.0, "retirementEmployer": 1.0, "medicalEmployee": 1.0, "medicalEmployer": 1.0, "medicalTaxCredit": 1305.0, "fringeBenefits": 1.0, "overtime": 0.0, "commission": 0.0, "travelAllowance": 0.0, "otherAllowances": 0.0, "fringeAccommodation": 0.0, "fringeMedicalCosts": 0.0 }, "provenance": { "source": "referral", "sourceLabel": "Karoo Fresh Holdings Ltd", "capturedAt": "2026-09-01T09:15:00Z", "capturedBy": "text", "note": "Budget deferred to the next financial year.", "method": "eft" }, "issues": [], "derivedPeriodsWorked": 1, "periodsRunInLedgr": 1 } ], "statedCount": 3, "employeeCount": 3, "totalRemuneration": 10005.0, "totalPaye": 12400.0, "totalUif": 1062.72, "totalSdl": 890.0, "blockingCount": 3, "warningCount": 3 } }, "GetApiPayslipsByIdResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "periodId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "payDate": "2026-09-01", "basicSalary": 1.0, "travelAllowance": 1.0, "overtime": 1.0, "commission": 1.0, "bonus": 1.0, "otherAllowances": 1.0, "grossSalary": 1.0, "pensionContribution": 1.0, "medicalAidContribution": 1.0, "employerRetirement": 1.0, "employerMedical": 1.0, "thirdPartyDeductions": 1.0, "taxableRemuneration": 1305.0, "travelInclusionRate": 15.0, "payeTax": 1305.0, "uifEmployee": 1.0, "uifEmployer": 1.0, "sdl": 1.0, "netPay": 8700.0, "ytdGross": 1.0, "ytdPaye": 1.0, "hoursWorked": 3.0, "etiHoursSource": "referral", "etiAmount": 10005.0, "etiReason": "Budget deferred to the next financial year.", "catchUpPaye": 1.0, "catchUpNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "deductionLines": [ { "beneficiaryName": "Karoo Fresh Holdings Ltd", "reference": "INV-0001", "employeeAmount": 10005.0, "employerAmount": 10005.0 } ], "fringeBenefitsOtherRemuneration": 1.0, "status": "sent", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "GetApiPractitionerAccountTemplatesResponseExample": { "description": "Shared by 3 operations.", "value": { "promise": "Applying a template only ADDS accounts. It never renames, moves or removes anything the client already has, so it is safe on a client with a full set of books.", "templates": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Restaurants", "lineCount": 12, "sourceName": "Thabo Restaurants", "capturedAt": "2026-09-01T09:15:00Z", "summary": "12 accounts on top of the standard chart · from Thabo Restaurants · 2026-09-01", "lines": [ { "code": "6410", "name": "Kitchen consumables", "accountType": "expense", "normalBalance": "debit", "accountSubtype": "operating_expense", "parentCode": "6400", "cashFlowSection": "operating", "isContra": false } ] } ] } }, "GetApiPractitionerClientsByIdFieldsResponseExample": { "description": "Shared by 5 operations.", "value": { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Acme Trading (Pty) Ltd", "summary": "Partner: AC · Cycle: Monthly", "fields": [ { "fieldId": "8d21b6e0-77c4-4a15-9f30-1b5e9c2a7d64", "name": "Partner", "kind": "text", "value": "AC", "display": "AC" }, { "fieldId": "b41f0c93-2ad8-4e77-8c16-5f9e3d0a2b18", "name": "Cycle", "kind": "text", "value": "Monthly", "display": "Monthly" } ] } }, "GetApiPractitionerClientsByIdStaffResponseExample": { "description": "Shared by 3 operations.", "value": { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Karoo Fresh Holdings Ltd", "inviteeEmail": "thabo@mokoenapartners.example", "inviteeName": "Thabo Nkosi", "assigned": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Ayesha Patel", "email": "ayesha@mokoenapartners.example", "roleName": "Accountant", "isSelf": false } ], "roster": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Ayesha Patel", "email": "ayesha@mokoenapartners.example", "roleName": "Accountant", "isSelf": false } ], "clientIsTold": "Mokoena Partners has also assigned Ayesha Patel to your books. They work under the same access you granted, for fifteen minutes at a time, and everything each of them does is recorded against their own name in your audit trail." } }, "GetApiPractitionerDirectoryListingResponseExample": { "description": "Shared by 2 operations.", "value": { "exists": false, "optedIn": false, "displayName": "Karoo Fresh Holdings Ltd", "town": "text", "province": "Western Cape", "services": [ "text" ], "contactEmail": "accounts@karoofresh.example", "website": "https://app.ledgrsa.com/pay/3f1a7c92", "hidden": false, "hiddenReason": "Budget deferred to the next financial year.", "listed": false, "eligible": false, "summary": "Consulting services — August 2026" } }, "GetApiPractitionerProfessionalRegistrationResponseExample": { "description": "Shared by 2 operations.", "value": { "status": "submitted", "body": "saica", "bodyLabel": "SAICA", "membershipNumber": "20012345", "decisionNote": null, "submittedAt": "2026-09-01T09:15:00Z", "decidedAt": null, "payoutHeld": true, "rungLabel": "Bronze", "rungPercent": 15.0, "summary": "text" } }, "GetApiPractitionerQueriesByIdFilesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subjectType": "general", "subjectLabel": "February 2026", "question": "Please send the February bank statement and the vehicle finance agreement.", "kind": "documents", "dueDate": "2026-09-30", "status": "answered", "statusWord": "Answered — 1 sent", "clientNote": "Your accountant asked for these by 30 September 2026.", "fileCount": 1, "priority": "normal", "askedByEmail": "owner.prac@ledgraudit.test", "createdAt": "2026-09-01T09:15:00Z", "files": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "filename": "february-bank-statement.pdf", "caption": "February statement", "contentType": "application/pdf", "sizeBytes": 184320, "uploadedAt": "2026-09-01T09:15:00Z", "uploadedByName": "Thandi Nkosi", "url": "https://storage.example/ledgr/signed/february-bank-statement.pdf" } ] } }, "GetApiPractitionerReportTemplatesResponseExample": { "description": "Shared by 3 operations.", "value": { "templates": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Month end", "actionIds": [ "vat201-check", "emp201-check" ], "summary": "Check the VAT201 before filing, then check last month's EMP201", "createdAt": "2026-11-01T09:15:00Z" } ], "promise": "A template runs the checks you chose, in that order, for the clients you tick - each under that client's own access. It reads, or prepares a draft. It never files anything." } }, "GetApiProcurementRequisitionsByIdBudgetImpactResponseExample": { "description": "Shared by 2 operations.", "value": [ { "budgetId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "budgetName": "Karoo Fresh Holdings Ltd", "policy": "fifo", "budget": 1.0, "actual": 1.0, "committed": 1.0, "thisPurchase": 1.0, "available": 1.0, "remainingAfter": 1.0, "overBy": 1.0, "exceeded": true, "needsExtraApproval": true, "summary": "Consulting services — August 2026", "approvalStatus": "sent", "canDecide": true, "decisionComment": "Budget deferred to the next financial year." } ] }, "GetApiProcurementSupplierRegistrationLinkResponseExample": { "description": "Shared by 2 operations.", "value": { "enabled": true, "url": "https://app.ledgrsa.com/pay/3f1a7c92", "token": "", "intro": "text", "requiredDocuments": [ "text" ], "unavailableReason": "Budget deferred to the next financial year." } }, "GetApiProcurementSuppliersByContactIdPunchoutResponseExample": { "description": "Shared by 2 operations.", "value": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "protocol": "text", "setupUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "fromIdentity": "text", "toIdentity": "text", "senderIdentity": "text", "username": "text", "hasSecret": false, "active": false, "configured": false } }, "GetApiPurchaseOrdersByIdResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "INV-0001", "supplierName": "Karoo Fresh Holdings Ltd", "issueDate": "2026-09-01", "expectedDate": "2026-09-01", "status": "sent", "total": 10005.0, "outstandingValue": 10005.0, "lines": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyOrdered": 1.0, "qtyReceived": 1.0, "qtyOutstanding": 1.0, "unitPrice": 2900.0 } ], "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptCount": 3 } }, "GetApiPurchaseOrdersResponseExample": { "description": "Shared by 2 operations.", "value": { "asOf": "text", "orders": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "INV-0001", "supplierName": "Karoo Fresh Holdings Ltd", "issueDate": "2026-09-01", "expectedDate": "2026-09-01", "status": "sent", "total": 10005.0, "outstandingValue": 10005.0, "lines": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyOrdered": 1.0, "qtyReceived": 1.0, "qtyOutstanding": 1.0, "unitPrice": 2900.0 } ], "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptCount": 3 } ], "totalOutstanding": 10005.0, "openOrderCount": 3 } }, "GetApiReconciliationByIdResponseExample": { "description": "Shared by 7 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "statementBalance": 10005.0, "openingBalance": 10005.0, "clearedBalance": 10005.0, "difference": 1.0, "clearedIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "status": "OPEN", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "GetApiRecurringByIdLeaseDepositResponseExample": { "description": "Shared by 4 operations.", "value": { "leaseId": "5b1e9c3a-7d2f-4e8a-9c10-2f3a4b5c6d7e", "required": 20000.0, "held": 18000.0, "movements": [ { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "kind": "taken", "amount": 20000.0, "on": "2026-03-01", "method": "eft", "reference": "Deposit 1A", "journalId": "3f2e1d0c-9b8a-4766-8554-433221100ffe" }, { "id": "8b7c6d5e-4f3a-4b2c-9d1e-0f9a8b7c6d5e", "kind": "applied", "amount": 2000.0, "on": "2026-09-30", "invoiceId": "d4c3b2a1-0f9e-4d8c-8b7a-695847362514" } ] } }, "GetApiRecurringByIdLeaseResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "5b1e9c3a-7d2f-4e8a-9c10-2f3a4b5c6d7e", "scheduleId": "a3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e", "propertyId": "7d0c2f4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "propertyName": "12 Main Street", "unit": "1A", "startDate": "2026-03-01", "endDate": "2029-02-28", "contactId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "contactName": "Unit Tenant", "rent": 10800.0, "frequency": "monthly", "escalationPercent": 8.0, "escalationDate": "2027-03-01", "escalationMonths": 12, "nextRent": 11664.0, "deposit": 20000.0 } }, "GetApiRentalContractsByIdDepositResponseExample": { "description": "Shared by 3 operations.", "value": { "contractId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "held": 1.0, "movements": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "amount": 10005.0, "on": "2026-09-01", "method": "eft", "reference": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "awaitingPayout": false } ], "links": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "url": "https://app.ledgrsa.com/pay/3f1a7c92", "gateway": "payfast", "amount": 10005.0, "status": "sent", "paidAt": "2026-09-01T09:15:00Z" } ] } }, "GetApiRentalContractsByIdResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contractNumber": "INV-0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "site": "text", "status": "sent", "outDate": "2026-09-01", "dueBack": "text", "offHiredOn": "2026-09-01", "offHireRequestedBy": "text", "offHireRequestedAt": "2026-09-01T09:15:00Z", "delivery": false, "collection": false, "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hireItemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "kind": "standard", "quantity": 3, "qtyOut": 3, "qtyBack": 3, "qtyMissing": 3, "withCustomer": 1, "toGo": 1, "offHiredOn": "2026-09-01", "hireCharge": 1.0, "periods": "2026-09", "meterUnit": "each", "meterOut": 1.0, "crossHired": false, "supplierName": "Karoo Fresh Holdings Ltd" } ], "charges": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "description": "Consulting services — August 2026", "quantity": 1, "unitAmount": 10005.0, "total": 10005.0 } ], "stops": [ { "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "stopType": "standard", "status": "sent", "hasProof": false } ], "photoCount": 3, "depositHeld": 1.0, "total": 10005.0, "billing": "text", "invoices": [ { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "kind": "invoice", "from": "2026-09-01", "to": "2026-09-30", "status": "sent", "total": 10005.0, "amountDue": 10005.0 } ] } }, "GetApiReportsAgedDebtorsResponseExample": { "description": "Shared by 2 operations.", "value": { "asOfLabel": "Karoo Fresh Holdings Ltd", "buckets": [ { "label": "Karoo Fresh Holdings Ltd", "amount": 10005.0, "colorHex": "#0D47A1" } ], "total": 10005.0, "ledgerControlBalance": 10005.0, "controlDifference": 1.0 } }, "GetApiReportsAuditTrailResponseExample": { "description": "Shared by 2 operations.", "value": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "actorUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "actorEmail": "accounts@karoofresh.example", "actorName": "Karoo Fresh Holdings Ltd", "action": "created", "resourceType": "standard", "resourceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "severity": "text", "payload": "text", "ipAddress": "12 Long Street, Cape Town, 8001", "userAgent": "text", "createdAt": "2026-09-01T09:15:00Z" } ], "total": 42, "page": 1, "limit": 50 } }, "GetApiReportsBreakEvenResponseExample": { "description": "Shared by 2 operations.", "value": { "periodLabel": "2026-09", "from": "2026-09-01", "to": "2026-09-30", "revenue": 1.0, "variableCosts": 10005.0, "fixedCosts": 10005.0, "contributionMargin": 1.0, "contributionMarginRatio": 1.0, "breakEvenRevenue": 1.0, "marginOfSafety": 1.0, "marginOfSafetyRatio": 1.0, "operatingProfit": 1.0, "costOfSales": 10005.0, "operatingExpenses": 1.0, "tiesToIncomeStatement": true, "notComputable": "text", "accounts": [ { "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "section": "text", "amount": 10005.0, "behaviour": "text", "stated": true } ] } }, "GetApiReportsSummaryResponseExample": { "description": "Shared by 2 operations.", "value": { "ytdRevenue": 1.0, "netProfit": 8700.0, "totalAssets": 10005.0, "outstanding": 1.0, "bbbeeScored": 1, "bbbeeMax": 1, "bbbeeLevel": 1, "grossMarginPct": 1, "netMarginPct": 1, "periodLabel": "2026-09", "monthlyTrend": [ { "month": "2026-09", "revenue": 1.0, "expenses": 1.0, "cogs": 1.0, "outputVat": 1305.0 } ], "cash": { "asOfLabel": "Karoo Fresh Holdings Ltd", "ledgerBalance": 10005.0, "cashAtBank": 1.0, "overdrafts": 1.0, "statementBalance": 10005.0, "unreconciledDifference": 1.0 } } }, "GetApiSarsDocumentsIrp6ResponseExample": { "description": "Shared by 4 operations.", "value": { "taxType": "VAT201", "title": "Karoo Fresh Holdings Ltd", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "periodLabel": "2026-09", "entityName": "Karoo Fresh Holdings Ltd", "taxReferenceNumber": "INV-0001", "sections": [ { "title": "Karoo Fresh Holdings Ltd", "note": "Budget deferred to the next financial year.", "fields": [ { "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "kind": "invoice", "amount": 10005.0, "display": "text", "unmapped": false, "confidence": "text", "note": "Budget deferred to the next financial year." } ] } ], "issues": [], "blockingIssues": [ "The control account and the age analysis differ by R0.00." ], "warnings": [], "unmappedFields": [ "text" ], "unverifiedFieldCodes": [ "CT-001" ], "derivedPaymentReference": "INV-0001", "netAmount": 8700.0, "isRefund": false, "availableFormats": [ "CSV" ], "manualSubmissionOnly": true } }, "GetApiSarsDocumentsIt3dResponseExample": { "description": "Shared by 3 operations.", "value": { "taxType": "VAT201", "title": "Karoo Fresh Holdings Ltd", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "periodLabel": "2026-09", "entityName": "Karoo Fresh Holdings Ltd", "taxReferenceNumber": "INV-0001", "sections": [ { "title": "Karoo Fresh Holdings Ltd", "note": "Budget deferred to the next financial year.", "fields": [ { "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "kind": "invoice", "amount": 10005.0, "display": "text", "unmapped": false, "confidence": "text", "note": "Budget deferred to the next financial year." } ] } ], "issues": [], "blockingIssues": [ "The control account and the age analysis differ by R0.00." ], "warnings": [], "unmappedFields": [ "text" ], "unverifiedFieldCodes": [ "CT-001" ], "derivedPaymentReference": "INV-0001", "netAmount": 8700.0, "isRefund": false, "availableFormats": "html", "manualSubmissionOnly": true } }, "GetApiSarsPrepaidExpensesResponseExample": { "description": "Shared by 3 operations.", "value": { "asOf": "2026-02-28", "expenses": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a04", "description": "Software licence, 12 months", "paidOn": "2025-12-01", "amount": 60000.0, "serviceStart": "2025-12-01", "serviceEnd": "2026-11-30", "exempt": true, "exemptReason": "R100 000 or less", "unexpired": 45205.48, "expenseAccountCode": "6230", "released": 14794.52 } ], "unexpired": 45205.48, "deductedWhenPaid": 45205.48, "accountBalance": 45205.48, "unclassified": 0.0 } }, "GetApiSarsSbcResponseExample": { "description": "Shared by 2 operations.", "value": { "yearEnd": "2027-02-28", "shareholdersAllNaturalPersons": true, "grossIncomeWithinLimit": true, "noSharesInOtherCompanies": true, "investmentAndServiceIncomeWithinLimit": true, "notPersonalServiceProvider": true, "qualifies": true, "confirmedAt": "2026-10-13T08:00:00Z", "grossIncomeOnLedger": 500000.0 } }, "GetApiSarsSection24cClaimsResponseExample": { "description": "Shared by 3 operations.", "value": { "yearEnd": "2026-02-28", "claims": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "yearEnd": "2026-02-28", "contractRef": "SLA-2025-14", "contractDate": "2025-11-03", "incomeReceivedInAdvance": 18000.0, "futureExpenditure": 10000.0, "allowance": 10000.0 } ], "claimed": 10000.0, "incomeReceivedInAdvance": 18000.0, "allowed": 10000.0 } }, "GetApiSarsTurnoverTaxResponseExample": { "description": "Shared by 2 operations.", "value": { "taxYearEndYear": 2027, "periodStart": "2026-03-01", "periodEnd": "2027-02-28", "registered": true, "turnoverToDate": 600000.0, "completedMonths": 6, "projectedTurnover": 1200000.0, "taxOnTurnoverToDate": 0.0, "estimatedTax": 8500.0, "firstInterim": { "amount": 4250.0, "dueDate": "2026-08-31" }, "secondInterim": { "amount": 4250.0, "dueDate": "2027-02-26" }, "annualReturnOpens": "2027-07-01", "annualReturnDue": "2028-01-31", "turnoverLimit": 2300000.0, "issues": [] } }, "GetApiSarsVatReviewResponseExample": { "description": "Shared by 4 operations.", "value": { "findings": [ { "key": "disposal:3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "disposal_no_output_tax", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "filed": true, "reference": "FA-0001", "message": "Press was sold for R115 000.00 and no output tax was declared on it.", "vatEffect": 15000.0, "check": false, "route": "correction", "press": "book_output_tax", "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "decision": null, "decisionReason": null } ] } }, "GetApiSuppliersByIdBankDetailsResponseExample": { "description": "Shared by 2 operations.", "value": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "bankName": "FNB", "accountNumber": "62012345678", "branchCode": "250655", "accountType": "savings", "updatedAt": "2026-09-01T09:15:00Z", "updatedByName": "Thandi Mokoena", "blocker": "text" } }, "GetApiTenantSettingsResponseExample": { "description": "Shared by 2 operations.", "value": { "taxVat": { "isVatRegistered": true, "vatRegistrationDate": "2026-09-01", "vatPeriod": "2026-09", "standardVatRate": 15.0, "drcEnabled": false, "provisionalTaxPayer": true, "sarsIsvConnected": false, "sarsTaxRefNumber": "INV-0001", "incomeTaxRate": 15.0 }, "branding": { "brandColorHex": "#0D47A1" }, "localisation": { "currency": "ZAR", "dateFormat": "day-month-year", "numberFormat": "space-point" }, "integrations": { "key": true }, "notifications": { "key": true }, "dataPrefs": { "autoBackupEnabled": true, "autoBackupFrequency": "monthly", "retentionMonths": 84 } } }, "GetApiTimeTrackingProjectsByIdMilestonesResponseExample": { "description": "Shared by 3 operations.", "value": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0, "dueDate": "2026-09-01", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001" } ] }, "GetApiWorkOrdersByIdNonConformancesResponseExample": { "description": "Shared by 2 operations.", "value": { "boards": [ { "id": "2d4e0a00-1111-4222-8333-944455556666", "name": "Non-conformances" } ], "items": [ { "id": "3e5f0a00-1111-4222-8333-944455556666", "itemKey": "NCR-0007", "title": "Hinge gap out of tolerance", "boardName": "Non-conformances", "stage": "Raised", "closed": false, "createdAt": "2026-09-28T08:20:00Z", "lotNumber": "LOT-7" } ], "mayRaise": true } }, "GetApiWorkOrdersByIdOperationsResponseExample": { "description": "Shared by 11 operations.", "value": { "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "status": "sent", "productName": "Karoo Fresh Holdings Ltd", "routingId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "routingName": "Karoo Fresh Holdings Ltd", "expectedYieldPercent": 15.0, "qtyPlanned": 1.0, "qtyToStart": 1.0, "qtyCompleted": 1.0, "qtyScrapped": 1.0, "operations": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "routingOperationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sequenceNo": 1, "description": "Consulting services — August 2026", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workCentreCode": "CT-001", "workCentreName": "Karoo Fresh Holdings Ltd", "status": "sent", "plannedSetupHours": 3.0, "plannedRunHours": 3.0, "plannedHours": 3.0, "actualHours": 3.0, "varianceHours": 3.0, "qtyCompleted": 1.0, "qtyScrapped": 1.0, "labourRatePerHour": 1.0, "overheadRatePerHour": 1.0, "actualCost": 10005.0, "plannedCost": 10005.0, "isSubcontract": false, "subcontractSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subcontractSupplierName": "Karoo Fresh Holdings Ltd", "scheduledStart": "2026-09-01", "scheduledFinish": "text", "startedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "operatorName": "Karoo Fresh Holdings Ltd", "notes": "Budget deferred to the next financial year." } ], "operationCount": 3, "completedOperationCount": 3, "percentComplete": 15.0, "plannedHours": 3.0, "actualHours": 3.0, "varianceHours": 3.0, "actualLabourCost": 10005.0, "currentOperation": "text" } }, "GetApiWorkOrdersByIdSubcontractOrdersResponseExample": { "description": "Shared by 2 operations.", "value": { "orders": [ { "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "status": "sent", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "operationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "step": "text", "qtyOrdered": 1.0, "qtyReceived": 1.0, "unitCost": 2900.0, "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "source": "referral" } ], "note": "Budget deferred to the next financial year." } }, "GetApiWorkOrdersOperationsByOpIdChecksResponseExample": { "description": "Shared by 2 operations.", "value": { "items": [ { "id": "8b2e0a00-1111-4222-8333-944455556666", "operationId": "7d2e1a00-1111-4222-8333-944455556666", "label": "Gap between frame and hinge", "kind": "measure", "minValue": 4.5, "maxValue": 5.5, "unit": "mm", "result": "fail", "measuredValue": 5.9, "notes": null, "recordedByName": "Thabo Nkosi", "recordedAt": "2026-09-28T08:14:00Z" } ] } }, "GetApiWorkOrdersOperationsByOpIdFreeIssueResponseExample": { "description": "Shared by 3 operations.", "value": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "unit": "each", "location": "text", "sent": 1.0, "consumed": 1.0, "returned": 1.0, "atSubcontractor": 1.0, "perUnit": 1.0 } ] }, "GetDriverApiV1ExceptionReasonsResponseExample": { "description": "Shared by 2 operations.", "value": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "category": "Office supplies", "isFailure": true, "isChargeable": false, "sortOrder": 1, "active": true } ] }, "GetDriverApiV1TripsByIdMessagesResponseExample": { "description": "Shared by 2 operations.", "value": { "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "driverName": "Thandi Mokoena", "messages": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sender": "office", "senderName": "Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached.", "photoUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "clientSeq": 1, "writtenAt": "2026-09-01T09:15:00Z", "deliveredAt": "2026-09-01T09:15:00Z", "readAt": "2026-09-01T09:15:00Z" } ], "unread": 1 } }, "PatchApiContactsByIdRequestExample": { "description": "Shared by 2 operations.", "value": { "editId": "9b2e4c61-7a3d-4f58-8e0c-1d6a5b3c2f47", "base": { "email": "accounts@capeunion.example" }, "changes": { "email": "finance@capeunion.example" }, "baseUpdatedAt": "2026-09-01T09:15:00Z", "conflicts": [] } }, "PostApiAccountsResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "parentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "accountType": "asset", "accountSubtype": "text", "currency": "ZAR", "isActive": true, "isSystem": false, "normalBalance": "text", "children": [ null ] } }, "PostApiBankAccountsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "accountNumber": "62012345678", "bankName": "FNB", "currency": "ZAR", "currentBalance": 10005.0, "statementBalance": 10005.0, "type": "standard", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiBankRulesApplyResponseExample": { "description": "Shared by 2 operations.", "value": { "matched": 1, "categorised": 1, "created": 1, "skipped": 1, "dryRun": true, "outcomes": [ { "transactionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "amount": 10005.0, "ruleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ruleName": "Karoo Fresh Holdings Ltd", "category": "Office supplies", "createKind": "standard", "createdId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "skippedReason": "Budget deferred to the next financial year." } ] } }, "PostApiBankRulesResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "conditions": "text", "action": "created", "priority": 1, "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiBankStatementsConvertResponseExample": { "description": "Shared by 2 operations.", "value": { "format": "CSV", "detected": "text", "accountReference": "INV-0001", "currency": "ZAR", "statementStart": "2026-09-01", "statementEnd": "2026-09-30", "openingBalance": 10005.0, "closingBalance": 10005.0, "bankProfile": { "bank": "FNB", "label": "Karoo Fresh Holdings Ltd", "confidence": 1.0, "evidence": [ "text" ], "matched": false, "source": "referral" }, "total": 42, "newCount": 3, "duplicateCount": 3, "balances": true, "balanceDifference": 10005.0, "rows": [ { "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "reference": "INV-0001", "runningBalance": 10005.0 } ], "issues": [], "warnings": [], "documentText": "text", "pageCount": 3, "pagesRead": 1, "truncated": false, "exactText": false, "readBy": "text" } }, "PostApiBankTransactionsResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "reference": "INV-0001", "type": "standard", "status": "UNRECONCILED", "matchedInvoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "matchedExpenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "category": "Office supplies", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "source": "referral", "autoCreatedKind": "standard", "autoCreatedId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct." } }, "PostApiBankTransfersResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromBankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromBankAccountName": "FNB Business Cheque", "toBankAccountId": "8c2d5e41-77b9-4a30-8e15-9f6b1d2c4a07", "toBankAccountName": "Standard Bank Business Savings", "transferDate": "2026-09-14", "amountOut": 5000.0, "amountIn": 5000.0, "currency": "ZAR", "outLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "inLineId": "8c2d5e41-77b9-4a30-8e15-9f6b1d2c4a07", "summary": "R 5 000.00 from FNB Business Cheque to Standard Bank Business Savings on 14 Sep 2026.", "ledgerNotice": null, "awaitingOtherSide": false } }, "PostApiBillsByBillIdCreditNotesResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "creditNoteNumber": "CN-0001", "issueDate": "2026-09-01", "creditedBillId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "creditedBillNumber": "CN-0001", "supplierName": "Karoo Fresh Holdings Ltd", "net": 8700.0, "vat": 1305.0, "total": 10005.0, "settlement": "text", "status": "sent", "reason": "Budget deferred to the next financial year.", "supplierReturnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "refundedAt": "2026-09-01T09:15:00Z" } }, "PostApiBillsByIdPaymentsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amountPaid": 0.0, "amountDue": 10005.0, "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis2Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis3Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendor": "Karoo Fresh Holdings Ltd", "billNumber": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "amount": 10005.0, "vatAmount": 1305.0, "vatRate": 15.0, "currency": "ZAR", "category": "Office supplies", "status": "sent", "recurring": false, "frequency": "monthly", "nextDate": "2026-09-01", "endDate": "2026-09-30", "recurrenceActive": true, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "paidAt": "2026-09-01T09:15:00Z", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobNumber": "JC-0001", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "kind": "standard", "creditedBillId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "discountRate": 0.0, "discountFixed": 0.0, "lineTotal": 10005.0, "vatAmount": 1305.0, "category": "Office supplies", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vatType": "standard", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "customsReference": null, "openMarketValue": null } ], "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "paymentHold": "text", "exchangeRate": 1.0, "paymentFxRate": 15.0, "baseGross": 1.0, "approvalStatus": "approved", "approvedBy": "Thandi Mokoena", "approvedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "rejectionReason": "Budget deferred to the next financial year.", "approvalProgress": { "given": 1, "needed": 1, "approverNames": [ "Thandi Mokoena" ], "youApproved": false }, "documentUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "documentVatUnclaimed": 1305.0, "vatNotices": [ { "code": "CT-001", "message": "Saved.", "redateTo": "2026-09-30" } ], "inputVatNotClaimed": 1305.0, "sellerDeclarationUrl": null, "sellerDeclarationSignedOn": null } }, "PostApiBillsByIdRejectResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendor": "Karoo Fresh Holdings Ltd", "billNumber": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "amount": 10005.0, "vatAmount": 1305.0, "vatRate": 15.0, "currency": "ZAR", "category": "Office supplies", "status": "sent", "recurring": false, "frequency": "monthly", "nextDate": "2026-09-01", "endDate": "2026-09-30", "recurrenceActive": true, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "paidAt": "2026-09-01T09:15:00Z", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobNumber": "JC-0001", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "kind": "standard", "creditedBillId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "discountRate": 0.0, "discountFixed": 0.0, "lineTotal": 10005.0, "vatAmount": 1305.0, "category": "Office supplies", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "customsReference": null, "openMarketValue": null } ], "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "paymentHold": "text", "exchangeRate": 1.0, "paymentFxRate": 15.0, "baseGross": 1.0, "approvalStatus": "approved", "approvedBy": "Thandi Mokoena", "approvedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "rejectionReason": "Budget deferred to the next financial year.", "approvalProgress": { "given": 1, "needed": 1, "approverNames": [ "Thandi Mokoena" ], "youApproved": false }, "sellerDeclarationUrl": null, "sellerDeclarationSignedOn": null } }, "PostApiBillsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendor": "Karoo Fresh Holdings Ltd", "billNumber": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "amount": 10005.0, "vatAmount": 1305.0, "vatRate": 15.0, "currency": "ZAR", "category": "Office supplies", "status": "sent", "recurring": false, "frequency": "monthly", "nextDate": "2026-09-01", "endDate": "2026-09-30", "recurrenceActive": true, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "paidAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "discountRate": 0.0, "discountFixed": 0.0, "lineTotal": 10005.0, "vatAmount": 1305.0, "category": "Office supplies", "customsReference": null, "openMarketValue": null } ], "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "sellerDeclarationUrl": null, "sellerDeclarationSignedOn": null } }, "PostApiBomRequestExample": { "description": "Shared by 2 operations.", "value": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "outputs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "kind": "co", "qtyPerRun": 1.0, "unitValue": 10005.0, "sharePercent": 15.0, "sortOrder": 1, "notes": "Budget deferred to the next financial year." } ], "kind": "standard", "name": "Standard build", "version": "1", "outputQty": 1.0, "labourCost": 250.0, "overheadCost": 80.0, "status": "active", "notes": "Two people, one shift", "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentVariantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentName": "Karoo Fresh Holdings Ltd", "componentSku": "LEN-TP-14G4", "qtyPer": 4.0, "scrapPercent": 2.5, "notes": "Cut to length", "sortOrder": 0, "sourceOverride": "make", "leadTimeOffsetDays": 30, "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "positionRef": "INV-0001", "unit": "each", "operationSeq": 1 } ], "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } }, "PostApiBomResponseExample": { "description": "Shared by 7 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "version": "1", "outputQty": 3.0, "labourCost": 10005.0, "overheadCost": 10005.0, "status": "sent", "notes": "Budget deferred to the next financial year.", "lineCount": 3, "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentVariantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentName": "Karoo Fresh Holdings Ltd", "componentSku": "LEN-TP-14G4", "qtyPer": 1.0, "scrapPercent": 15.0, "notes": "Budget deferred to the next financial year.", "sortOrder": 1 } ], "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "submittedAt": "2026-09-01T09:15:00Z", "submittedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "approvedByName": "Thandi Mokoena", "decisionNote": "Budget deferred to the next financial year.", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena", "createdAt": "2026-09-01T09:15:00Z" } }, "PostApiCompaniesResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "parentCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registrationNumber": "2021/123456/07", "vatNumber": "4123456789", "vatCategory": "Office supplies", "taxNumber": "9012345678", "payeNumber": "INV-0001", "uifNumber": "INV-0001", "sdlNumber": "INV-0001", "tradingAs": "text", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "address": "12 Long Street, Cape Town, 8001", "companyType": "PTY", "fiscalYearEndMonth": 9, "baseCurrency": "ZAR", "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "hasPostedLedger": false } }, "PostApiConsolidationGroupsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "rootCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "baseCurrency": "ZAR", "reportingPeriodStart": "2026-09-01", "reportingPeriodEnd": "2026-09-30", "status": "DRAFT", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiContactsByIdSitesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "addressLine1": "12 Long Street", "addressLine2": "Woodstock", "suburb": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "province": "Western Cape", "latitude": 1.0, "longitude": 1.0, "locationSource": "referral", "isDefault": false } }, "PostApiCrmCampaignsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "channel": "email", "startDate": "2026-09-01", "endDate": "2026-09-30", "budget": 1.0, "spend": 1.0, "currency": "ZAR", "status": "sent", "targetAudience": "text", "notes": "Budget deferred to the next financial year.", "leadCount": 3, "convertedLeadCount": 3, "opportunityCount": 3, "wonCount": 3, "wonRevenue": 1.0, "weightedPipeline": 1.0, "roiPct": 1.0, "costPerLead": 10005.0, "conversionRatePct": 1.0, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiCrmLeadsResponseExample": { "description": "Shared by 4 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "companyName": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "source": "referral", "status": "sent", "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "estimatedValue": 10005.0, "currency": "ZAR", "campaignId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "campaignName": "Karoo Fresh Holdings Ltd", "notes": "Budget deferred to the next financial year.", "convertedContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "convertedAt": "2026-09-01T09:15:00Z", "lostReason": "Budget deferred to the next financial year.", "activityCount": 3, "openTaskCount": 3, "lastActivityAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiCrmOpportunitiesResponseExample": { "description": "Shared by 4 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stageId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stageName": "Karoo Fresh Holdings Ltd", "stageIsWon": false, "stageIsLost": false, "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "value": 10005.0, "currency": "ZAR", "probability": 15.0, "weightedValue": 10005.0, "expectedCloseDate": "2026-09-01", "source": "referral", "status": "sent", "lostReason": "Budget deferred to the next financial year.", "closedAt": "2026-09-01T09:15:00Z", "campaignId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "campaignName": "Karoo Fresh Holdings Ltd", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "kind": "PRODUCT", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productCode": "CT-001", "quantity": 3.0, "unitPrice": 2900.0, "unitCost": 2900.0, "discountRate": 0.0, "discountFixed": 0.0, "discountType": "PERCENT", "vatRate": 15.0, "vatInclusive": false, "notes": "Budget deferred to the next financial year.", "lineSubtotal": 8700.0, "discountAmount": 0.0, "vatAmount": 1305.0, "lineTotal": 10005.0 } ], "lineCount": 3, "totals": { "currency": "ZAR", "subtotal": 8700.0, "discountTotal": 0.0, "vatTotal": 1305.0, "netValue": 8700.0, "grossValue": 10005.0, "lineCount": 3, "margin": { "revenue": 1.0, "cost": 10005.0, "profit": 1.0, "marginPct": 1.0, "costKnownForAllLines": true } }, "decision": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "status": "sent", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena", "declineReason": "Budget deferred to the next financial year.", "awaitingDecision": false }, "ageDays": 30, "activityCount": 3, "openTaskCount": 3, "nextActivityDue": "text", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiCrmTargetsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "targetValue": 10005.0, "currency": "ZAR", "notes": "Budget deferred to the next financial year.", "actualValue": 10005.0, "attainmentPct": 1.0, "remaining": 1.0, "weightedForecast": 1.0, "isCurrent": false } }, "PostApiEmployeesResponseExample": { "description": "Shared by 3 operations.", "value": { "documentLanguage": "text", "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "firstName": "Karoo Fresh Holdings Ltd", "lastName": "Karoo Fresh Holdings Ltd", "idNumber": "INV-0001", "passportNumber": "INV-0001", "passportCountry": "South Africa", "addressLine1": "12 Long Street", "addressLine2": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "addressCountry": "South Africa", "asylumPermitNumber": "INV-0001", "natureOfPerson": "text", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "dateOfBirth": "1988-04-12", "employmentType": "standard", "contractorWorksAtPremises": true, "contractorIsSupervised": true, "contractorHasThreeEmployees": true, "contractorNonResident": true, "irp30Number": "INV-0001", "irp30ValidTo": "2026-09-30", "pspRegistrationType": "standard", "pspRegistrationNumber": "2021/123456/07", "noOtherEmployerDeclaration": true, "startDate": "2026-09-01", "endDate": "2026-09-30", "terminationReason": "Budget deferred to the next financial year.", "terminated": false, "jobTitle": "Karoo Fresh Holdings Ltd", "department": "Sales", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "bankName": "FNB", "bankAccountNumber": "62012345678", "bankBranchCode": "250655", "bankAccountType": "current", "paymentMethod": "eft", "secondBankName": "FNB", "secondBankAccountNumber": "62012345678", "secondBankBranchCode": "250655", "secondBankAccountType": "standard", "splitAmount": 10005.0, "splitPercent": 15.0, "minimumWageExemption": "text", "minimumWageExemptionUntil": "2026-09-30", "learnershipRegistrationNumber": "2021/123456/07", "learnershipNqfLevel": 1, "learnershipStart": "2026-09-01", "learnershipEnd": "2026-09-30", "learnershipDisability": true, "learnershipCompletedOn": "2026-09-01", "learnershipCreditsEarned": 1, "epwpWorker": true, "prescribedOfficer": false, "taxNumber": "9012345678", "uifLiable": true, "payFrequency": "MONTHLY", "basicSalary": 1.0, "travelAllowance": 1.0, "pensionContribution": 1.0, "medicalAidContribution": 1.0, "medicalAidMembers": 1, "travelInclusionRate": 15.0, "openingYtdTaxYearEnd": 1, "openingYtdRemuneration": 1.0, "openingYtdPaye": 1.0, "openingYtdAnnualPayments": 1.0, "openingYtdPayeOnAnnualPayments": 1.0, "leaveBalances": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leaveType": "annual", "balanceDays": 10005.0, "takenDays": 1.0 } ], "leaveDaysPerWeek": 5, "leaveWorksSundays": false, "leaveWeekdays": [ 1, 2, 3, 4, 5 ], "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiExpensesCategoriesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "fuel-and-tolls", "name": "Fuel and tolls", "color": "#0D47A1", "icon": "fuel", "sortOrder": 0, "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "productCount": 0 } }, "PostApiExpensesReceiptsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "contentType": "application/pdf", "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==" } }, "PostApiFixedAssetsResponseExample": { "description": "Shared by 4 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "assetNumber": "INV-0001", "name": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "assetClass": "text", "assetClassLabel": "Karoo Fresh Holdings Ltd", "acquisitionDate": "2026-09-01", "cost": 10005.0, "residualValue": 10005.0, "usefulLifeMonths": 1, "usefulLifeReliable": true, "method": "eft", "ratePercent": 15.0, "accumulatedDepreciation": 1.0, "bookValue": 10005.0, "depreciatedTo": "2026-09-30", "status": "sent", "disposalDate": "2026-09-01", "disposalProceeds": 1.0, "serialNumber": "INV-0001", "location": "text", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreCode": "CT-001", "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "monthsRemaining": 1 } }, "PostApiIntercompanyTransactionsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "transactionDate": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "currency": "ZAR", "exchangeRate": 1.0, "accountIdFrom": "2026-09-01", "accountIdTo": "2026-09-30", "status": "PENDING", "settledOn": "2026-09-01", "settledAt": "2026-09-01T09:15:00Z", "settledByName": "Karoo Fresh Holdings Ltd", "settlementReference": "INV-0001", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "kind": "trade" } }, "PostApiInventoryAdjustResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "category": "Office supplies", "costPrice": 10005.0, "sellPrice": 10005.0, "vatRate": 15.0, "stockQty": 3.0, "reorderPoint": 1.0, "unit": "each", "qtyPrecision": 3, "barcode": "6001234567890", "costingMethod": "eft", "isTracked": true, "stockValue": 10005.0, "tracksSerials": false, "warrantyMonths": 1, "imageIcon": "text", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiInventoryBomsRequestExample": { "description": "Shared by 2 operations.", "value": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "outputs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "kind": "co", "qtyPerRun": 1.0, "unitValue": 10005.0, "sharePercent": 15.0, "sortOrder": 1, "notes": "Budget deferred to the next financial year." } ], "kind": "standard", "name": "Karoo Fresh Holdings Ltd", "version": "1", "outputQty": 3.0, "labourCost": 10005.0, "overheadCost": 10005.0, "status": "active", "notes": "Budget deferred to the next financial year.", "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentVariantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentName": "Karoo Fresh Holdings Ltd", "componentSku": "LEN-TP-14G4", "qtyPer": 1.0, "scrapPercent": 15.0, "notes": "Budget deferred to the next financial year.", "sortOrder": 1, "sourceOverride": "make", "leadTimeOffsetDays": 30, "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "positionRef": "INV-0001", "unit": "each", "operationSeq": 1 } ], "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } }, "PostApiInventoryBomsResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "version": "1", "outputQty": 3.0, "labourCost": 10005.0, "overheadCost": 10005.0, "status": "sent", "notes": "Budget deferred to the next financial year.", "lineCount": 3, "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentVariantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentName": "Karoo Fresh Holdings Ltd", "componentSku": "LEN-TP-14G4", "qtyPer": 1.0, "scrapPercent": 15.0, "notes": "Budget deferred to the next financial year.", "sortOrder": 1 } ], "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "createdAt": "2026-09-01T09:15:00Z", "submittedAt": "2026-09-01T09:15:00Z", "submittedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "approvedByName": "Thandi Mokoena", "decisionNote": "Budget deferred to the next financial year.", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena" } }, "PostApiInventoryCategoriesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "color": "#0D47A1", "icon": "text", "description": "Consulting services — August 2026", "sortOrder": 1, "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiInventoryDisassembliesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "qty": 3.0, "parentValue": 10005.0, "partsValue": 10005.0, "residue": 1.0, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "brokenAt": "2026-09-01T09:15:00Z", "parts": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "qtyRecovered": 1.0, "unitCost": 2900.0, "value": 10005.0, "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } }, "PostApiInventoryLocationsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "address": "12 Long Street, Cape Town, 8001", "type": "standard", "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiInventoryPriceListsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "priceCount": 3, "customerCount": 3, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiInventoryProductsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "category": "Office supplies", "costPrice": 10005.0, "sellPrice": 10005.0, "vatRate": 15.0, "stockQty": 3.0, "reorderPoint": 1.0, "unit": "each", "units": { "key": 1.0 }, "qtyPrecision": 3, "barcode": "6001234567890", "weightKg": 1.0, "volumeM3": 1.0, "unitsPerPallet": 1.0, "costingMethod": "eft", "isTracked": true, "stockValue": 10005.0, "tracksSerials": false, "warrantyMonths": 1, "isSellable": false, "imageIcon": "text", "thumbnailUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiInventorySerialsByIdScrapResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "serialNumber": "INV-0001", "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplier": "Karoo Fresh Holdings Ltd", "receivedDate": "2026-09-01", "unitCost": 2900.0, "status": "sent", "soldDate": "2026-09-01", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "autoAssigned": false, "warrantyExpiry": "2026-09-30", "warrantyDaysRemaining": 30, "underWarranty": false, "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z" } }, "PostApiInventoryStockTakesResponseExample": { "description": "Shared by 5 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "name": "Karoo Fresh Holdings Ltd", "status": "sent", "startedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "lineCount": 3, "totalVariance": 10005.0, "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "sku": "LEN-TP-14G4", "expectedQty": 3.0, "countedQty": 3.0, "variance": 1.0 } ] } }, "PostApiInventoryVariantsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "attributes": "text", "costPrice": 10005.0, "sellPrice": 10005.0, "stockQty": 3.0, "barcode": "6001234567890", "isActive": true, "createdAt": "2026-09-01T09:15:00Z" } }, "PostApiInvoicesByIdApplyCreditResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "documentType": "invoice", "invoiceNumber": "INV-0001", "status": "sent", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "deliveryDate": "2026-09-01", "expectedPaymentDate": "2026-09-01", "currency": "ZAR", "exchangeRate": 1.0, "subtotal": 8700.0, "discountTotal": 0.0, "vatTotal": 1305.0, "total": 10005.0, "amountPaid": 0.0, "amountDue": 10005.0, "vatRegistered": true, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "terms": "30", "sourceDocumentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena", "declineReason": "Budget deferred to the next financial year.", "lastSendChannel": "email", "lastSendDelivered": true, "lastSendError": "text", "lastSendAt": "2026-09-01T09:15:00Z", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stockWarnings": [ "text" ], "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "discountRate": 0.0, "vatRate": 15.0, "vatInclusive": false, "lineSubtotal": 8700.0, "discountAmount": 0.0, "vatAmount": 1305.0, "lineTotal": 10005.0, "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "discountType": "PERCENT", "discountFixed": 0.0, "kind": "PRODUCT", "productCode": "CT-001", "warehouseBin": "A-12-03" } ], "payments": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "amount": 10005.0, "method": "eft", "reference": "INV-0001", "createdAt": "2026-09-01T09:15:00Z" } ], "reminders": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sentDate": "2026-09-01", "channel": "email", "createdAt": "2026-09-01T09:15:00Z", "status": "sent" } ], "contactRemindersPaused": false, "tcs": "Goods remain the property of the seller until paid in full.", "bankDetails": "FNB Business Account 62012345678, branch 250655", "footer": "Thank you for your business.", "deposit": { "percent": 15.0, "amount": 10005.0, "appliedTo": "2026-09-30" }, "picking": { "warehouse": "Cape Town HQ", "picker": "Thandi Mokoena", "lines": [ { "idx": 1, "picked": true } ] }, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "domesticReverseCharge": false, "paymentGateways": [ "payfast" ] } }, "PostApiInvoicesByIdSendResponseExample": { "description": "Shared by 2 operations.", "value": { "invoice": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "documentType": "invoice", "invoiceNumber": "INV-0001", "status": "sent", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "currency": "ZAR", "exchangeRate": 1.0, "subtotal": 8700.0, "discountTotal": 0.0, "vatTotal": 1305.0, "total": 10005.0, "amountPaid": 0.0, "amountDue": 10005.0, "vatRegistered": true, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "terms": "30", "sourceDocumentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena", "declineReason": "Budget deferred to the next financial year.", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "discountRate": 0.0, "vatRate": 15.0, "vatInclusive": false, "lineSubtotal": 8700.0, "discountAmount": 0.0, "vatAmount": 1305.0, "lineTotal": 10005.0, "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "discountType": "PERCENT", "discountFixed": 0.0, "kind": "PRODUCT", "productCode": "CT-001", "warehouseBin": "A-12-03" } ], "payments": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "amount": 10005.0, "method": "eft", "reference": "INV-0001", "createdAt": "2026-09-01T09:15:00Z" } ], "reminders": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sentDate": "2026-09-01", "channel": "email", "createdAt": "2026-09-01T09:15:00Z" } ], "contactRemindersPaused": false, "tcs": "Goods remain the property of the seller until paid in full.", "bankDetails": "FNB Business Account 62012345678, branch 250655", "footer": "Thank you for your business.", "deposit": { "percent": 15.0, "amount": 10005.0, "appliedTo": "2026-09-30" }, "picking": { "warehouse": "Cape Town HQ", "picker": "Thandi Mokoena", "lines": [ { "idx": 1, "picked": true } ] }, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" }, "channel": "email", "delivered": true, "deliveryError": "text", "portalUrl": "https://app.ledgrsa.com/pay/3f1a7c92" } }, "PostApiJobCardsByIdChecklistsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobNumber": "JC-0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "title": "Karoo Fresh Holdings Ltd", "workRequested": "text", "siteAddress": "12 Long Street, Cape Town, 8001", "siteContactName": "Karoo Fresh Holdings Ltd", "siteContactPhone": "+27 82 555 0143", "priority": "normal", "status": "sent", "scheduledStart": "2026-09-01", "scheduledEnd": "2026-09-30", "actualStart": "2026-09-01", "actualEnd": "2026-09-30", "quotedAmount": 10005.0, "currency": "ZAR", "sourceQuoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceQuoteNumber": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "invoicedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "signOffName": "Karoo Fresh Holdings Ltd", "signOffRole": "Accountant", "signOffSignature": "text", "signOffSignatureAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "signOffNotes": "Budget deferred to the next financial year.", "signOffAt": "2026-09-01T09:15:00Z", "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z", "technicians": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "isLead": false } ], "labour": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "technicianName": "Thandi Mokoena", "workDate": "2026-09-01", "hours": 3.0, "chargeRate": 15.0, "costRate": 15.0, "billable": true, "notes": "Budget deferred to the next financial year.", "timeEntryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "basis": "invoice", "units": 1.0, "unitLabel": "Karoo Fresh Holdings Ltd", "earningTypeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeName": "Karoo Fresh Holdings Ltd" } ], "parts": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "partCode": "CT-001", "qty": 3.0, "unitCost": 2900.0, "unitPrice": 2900.0, "billable": true, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "issued": false, "issuedAt": "2026-09-01T09:15:00Z", "issuedQty": 3.0, "stockMovementId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stockTracked": false } ], "costs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costType": "subcontractor", "description": "Consulting services — August 2026", "amount": 10005.0, "markupPercent": 15.0, "km": 1.0, "ratePerKm": 1.0, "billable": true, "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "incurredOn": "2026-09-01", "sourceExpenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceBillId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceReference": "INV-0001" } ], "statusHistory": [ { "fromStatus": "sent", "toStatus": "sent", "note": "Budget deferred to the next financial year.", "changedByName": "Karoo Fresh Holdings Ltd", "at": "2026-09-01T09:15:00Z" } ], "photos": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "phase": "before", "caption": "Serial plate before fitting", "sequence": 1, "takenByName": "Karoo Fresh Holdings Ltd", "takenAt": "2026-09-01T09:15:00Z" } ], "checklists": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "templateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "certificateTitle": "Karoo Fresh Holdings Ltd", "items": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd", "kind": "standard", "required": true, "ticked": false, "value": "text", "answeredBy": "text", "answeredAt": "2026-09-01T09:15:00Z" } ] } ], "costing": { "labourHours": 3.0, "labourCost": 10005.0, "labourBillable": 1.0, "partsCost": 10005.0, "partsBillable": 1.0, "otherCost": 10005.0, "otherBillable": 1.0, "actualCost": 10005.0, "billableValue": 10005.0, "quotedAmount": 10005.0, "quoteVariance": 1.0, "margin": 1.0, "marginPercent": 15.0 }, "allowedNextStatuses": [ "text" ] } }, "PostApiJobCardsChecklistTemplatesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "items": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd", "kind": "standard", "required": true } ], "certificateTitle": "Karoo Fresh Holdings Ltd" } }, "PostApiJobCardsMaintenanceResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "title": "Karoo Fresh Holdings Ltd", "workRequested": "text", "siteAddress": "12 Long Street, Cape Town, 8001", "siteContactName": "Karoo Fresh Holdings Ltd", "siteContactPhone": "+27 82 555 0143", "priority": "normal", "cadence": "text", "cadenceLabel": "Karoo Fresh Holdings Ltd", "anchorDate": "2026-09-01", "endsOn": "2026-09-01", "active": true, "leadUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leadUserName": "Karoo Fresh Holdings Ltd", "lastRaisedOn": "2026-09-01", "nextDueOn": "2026-09-01", "visitsOwed": 1, "visitsRaised": 1, "notes": "Budget deferred to the next financial year." } }, "PostApiJobCardsResponseExample": { "description": "Shared by 20 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobNumber": "JC-0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "title": "Karoo Fresh Holdings Ltd", "workRequested": "text", "siteAddress": "12 Long Street, Cape Town, 8001", "siteContactName": "Karoo Fresh Holdings Ltd", "siteContactPhone": "+27 82 555 0143", "priority": "normal", "status": "sent", "scheduledStart": "2026-09-01", "scheduledEnd": "2026-09-30", "actualStart": "2026-09-01", "actualEnd": "2026-09-30", "quotedAmount": 10005.0, "currency": "ZAR", "sourceQuoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceQuoteNumber": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "invoicedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "signOffName": "Karoo Fresh Holdings Ltd", "signOffRole": "Accountant", "signOffSignature": "text", "signOffSignatureAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "signOffNotes": "Budget deferred to the next financial year.", "signOffAt": "2026-09-01T09:15:00Z", "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z", "technicians": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "isLead": false } ], "labour": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "technicianName": "Thandi Mokoena", "workDate": "2026-09-01", "hours": 3.0, "chargeRate": 15.0, "costRate": 15.0, "billable": true, "notes": "Budget deferred to the next financial year.", "timeEntryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "parts": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "partCode": "CT-001", "qty": 3.0, "unitCost": 2900.0, "unitPrice": 2900.0, "billable": true, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "issued": false, "issuedAt": "2026-09-01T09:15:00Z", "issuedQty": 3.0, "stockMovementId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stockTracked": false } ], "costs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costType": "standard", "description": "Consulting services — August 2026", "amount": 10005.0, "markupPercent": 15.0, "km": 1.0, "ratePerKm": 1.0, "billable": true, "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "incurredOn": "2026-09-01", "sourceExpenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceBillId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceReference": "INV-0001" } ], "statusHistory": [ { "fromStatus": "sent", "toStatus": "sent", "note": "Budget deferred to the next financial year.", "changedByName": "Karoo Fresh Holdings Ltd", "at": "2026-09-01T09:15:00Z" } ], "photos": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "phase": "text", "caption": "Serial plate before fitting", "sequence": 1, "takenByName": "Karoo Fresh Holdings Ltd", "takenAt": "2026-09-01T09:15:00Z" } ], "costing": { "labourHours": 3.0, "labourCost": 10005.0, "labourBillable": 1.0, "partsCost": 10005.0, "partsBillable": 1.0, "otherCost": 10005.0, "otherBillable": 1.0, "actualCost": 10005.0, "billableValue": 10005.0, "quotedAmount": 10005.0, "quoteVariance": 1.0, "margin": 1.0, "marginPercent": 15.0 }, "allowedNextStatuses": [ "text" ] } }, "PostApiLandedCostsResponseExample": { "description": "Shared by 4 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "docketNumber": "INV-0001", "docketDate": "2026-09-01", "description": "Consulting services — August 2026", "vesselOrWaybill": "text", "customsMrn": "text", "allocationMethod": "eft", "status": "sent", "totalCharges": 10005.0, "totalCapitalised": 10005.0, "totalExpensed": 10005.0, "totalRecoverable": 10005.0, "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "postedAt": "2026-09-01T09:15:00Z", "notes": "Budget deferred to the next financial year.", "charges": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "chargeType": "standard", "label": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 10005.0, "capitalise": true, "expenseAccountCode": "CT-001" } ], "receiptIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "receiptNumbers": [ "INV-0001" ], "allocations": [ { "goodsReceiptLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "goodsReceiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "description": "Consulting services — August 2026", "qty": 3.0, "invoiceUnitCost": 2900.0, "lineValue": 10005.0, "basisAmount": 10005.0, "allocatedAmount": 10005.0, "landedUnitCost": 2900.0, "unitCostBefore": 2900.0, "unitCostAfter": 2900.0, "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "batchNumber": "INV-0001", "capitalisable": true } ], "isPreview": true, "uncapitalised": 1.0, "warnings": [] } }, "PostApiLeaveRequestsResponseExample": { "description": "Shared by 5 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "leaveType": "annual", "startDate": "2026-09-01", "endDate": "2026-09-30", "daysRequested": 1.0, "reason": "Budget deferred to the next financial year.", "status": "sent", "approvedBy": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z" } }, "PostApiLedgerCostCentresResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "kind": "standard", "parentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true } }, "PostApiLedgerJournalsResponseExample": { "description": "Shared by 4 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "journalNumber": "INV-0001", "journalDate": "2026-09-01", "sourceType": "invoice", "sourceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "memo": "text", "status": "sent", "totalDebit": 10005.0, "totalCredit": 10005.0, "reversedBy": "text", "reverses": "text", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountCode": "CT-001", "accountName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "debit": 1.0, "credit": 1.0, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "editable": false } }, "PostApiLedgerRecurringJournalsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "memo": "text", "reference": "INV-0001", "frequency": "monthly", "startDate": "2026-09-01", "endDate": "2026-09-30", "nextDate": "2026-09-01", "status": "active", "totalDebit": 10005.0, "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountCode": "CT-001", "accountName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "debit": 1.0, "credit": 1.0, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis2Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis3Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "runs": [ { "occurrenceDate": "2026-09-01", "outcome": "posted", "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "journalNumber": "INV-0001", "reason": "Budget deferred to the next financial year." } ] } }, "PostApiLogisticsDriversRequestExample": { "description": "Shared by 2 operations.", "value": { "settlementBasis": "drop", "settlementRate": 35, "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fullName": "Karoo Fresh Holdings Ltd", "phone": "+27 82 555 0143", "email": "accounts@karoofresh.example", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "licenceNumber": "INV-0001", "licenceCode": "CT-001", "licenceExpiry": "2026-09-30", "prdpNumber": "INV-0001", "prdpCategories": "G", "prdpExpiry": "2026-09-30", "status": "active", "defaultVehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } }, "PostApiLogisticsDriversResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fullName": "Karoo Fresh Holdings Ltd", "phone": "+27 82 555 0143", "email": "accounts@karoofresh.example", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "licenceNumber": "INV-0001", "licenceCode": "CT-001", "licenceExpiry": "2026-09-30", "prdpNumber": "INV-0001", "prdpCategories": "text", "prdpExpiry": "2026-09-30", "status": "active", "defaultVehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "defaultVehicleRegistration": "text", "notes": "Budget deferred to the next financial year.", "soonestDocumentExpiryDays": 30, "soonestDocumentExpiryKind": "standard", "appAccessIssued": false, "appAccessRevokedAt": "2026-09-01T09:15:00Z", "appLastSeenAt": "2026-09-01T09:15:00Z", "openTrips": 1 } }, "PostApiLogisticsExceptionReasonsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "category": "Office supplies", "isFailure": true, "isChargeable": false, "sortOrder": 1, "active": true } }, "PostApiLogisticsStandingRunsRequestExample": { "description": "Shared by 2 operations.", "value": { "runDays": [ 1, 3, 5 ], "name": "Karoo Fresh Holdings Ltd", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "cadence": "weekly", "startsOn": "2026-09-01", "endsOn": "2026-09-01", "active": true, "notes": "Budget deferred to the next financial year.", "stops": [ { "stopType": "delivery", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "contactPhone": "+27 82 555 0143", "address": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "instructions": "Budget deferred to the next financial year." } ], "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } }, "PostApiLogisticsStandingRunsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "cadence": "text", "cadenceLabel": "Karoo Fresh Holdings Ltd", "startsOn": "2026-09-01", "endsOn": "2026-09-01", "active": true, "notes": "Budget deferred to the next financial year.", "stops": [ { "stopType": "standard", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "contactPhone": "+27 82 555 0143", "address": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "instructions": "Budget deferred to the next financial year." } ], "nextRuns": [ "text" ] } }, "PostApiLogisticsTripsRequestExample": { "description": "Shared by 2 operations.", "value": { "tripDate": "2026-09-01", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "coDriverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "routeName": "Karoo Fresh Holdings Ltd", "plannedDeparture": "2026-10-01T07:00:00Z", "plannedReturn": "2026-10-01T16:00:00Z", "notes": "Budget deferred to the next financial year.", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } }, "PostApiLogisticsTripsResponseExample": { "description": "Shared by 4 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "tripDate": "2026-09-01", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "vehicleFleetNumber": "INV-0001", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "coDriverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "coDriverName": "Karoo Fresh Holdings Ltd", "status": "sent", "routeName": "Karoo Fresh Holdings Ltd", "plannedDeparture": "text", "actualDeparture": "text", "plannedReturn": "text", "actualReturn": "text", "startOdometerKm": 1.0, "endOdometerKm": 1.0, "odometerDistanceKm": 1.0, "trackedDistanceKm": 1.0, "fuelLitres": 1.0, "fuelCost": 10005.0, "fuelExpenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "cancelledReason": "Budget deferred to the next financial year.", "dispatchedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "stopCount": 3, "stopsCompleted": 1, "stopsFailed": 0, "stopsWithProof": 1, "litresPer100Km": 1.0, "costPerDrop": 10005.0, "currency": "ZAR", "stops": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "sequence": 1, "stopType": "delivery", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactDisplayName": "Karoo Fresh Holdings Ltd", "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "documentType": "invoice", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobCardNumber": "JC-0001", "stockLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "address": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "latitude": 1.0, "longitude": 1.0, "contactName": "Karoo Fresh Holdings Ltd", "contactPhone": "+27 82 555 0143", "instructions": "Budget deferred to the next financial year.", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "status": "sent", "enRouteAt": "2026-09-01T09:15:00Z", "arrivedAt": "2026-09-01T09:15:00Z", "departedAt": "2026-09-01T09:15:00Z", "arrivalLatitude": 1.0, "arrivalLongitude": 1.0, "arrivalAccuracyM": 1.0, "arrivalDistanceM": 1.0, "exceptionReasonCode": "CT-001", "exceptionReasonLabel": "Karoo Fresh Holdings Ltd", "exceptionNotes": "Budget deferred to the next financial year.", "stockPostedAt": "2026-09-01T09:15:00Z", "stockWarnings": [ "text" ], "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyOrdered": 1.0, "qtyDelivered": 1.0, "qtyReturned": 1.0, "uom": "each", "batchNumber": "INV-0001", "stockMovementId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "shortfall": 1.0, "qtyLoaded": 1.0, "loadCheckedAt": "2026-09-01T09:15:00Z", "service": false } ], "proof": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "outcome": "delivered", "receivedByName": "Karoo Fresh Holdings Ltd", "receivedByRole": "Accountant", "signatureAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "capturedLatitude": 1.0, "capturedLongitude": 1.0, "capturedAccuracyM": 1.0, "distanceFromStopM": 1.0, "capturedAt": "2026-09-01T09:15:00Z", "recordedAt": "2026-09-01T09:15:00Z", "clockSkewMinutes": 1, "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "deviceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "exceptionReasonCode": "CT-001", "exceptionReasonLabel": "Karoo Fresh Holdings Ltd", "photos": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "caption": "Serial plate before fitting", "sequence": 1 } ], "capturedInOffice": false, "learnableLocation": false, "strength": "STRONG", "evidenceStatement": "text", "weaknesses": [ "text" ] }, "collectable": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "amountDue": 10005.0, "foreignCurrency": "ZAR" }, "collection": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "paymentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 10005.0, "method": "cash", "reference": "INV-0001", "collectedAt": "2026-09-01T09:15:00Z", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "bankedAt": "2026-09-01T09:15:00Z", "bankingId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } ], "load": { "weightKg": 1.0, "volumeM3": 1.0, "pallets": 1, "payloadKg": 1.0, "vehicleVolumeM3": 1.0, "vehiclePallets": 1, "linesWithoutWeight": 1, "warnings": [] } } }, "PostApiLogisticsVehiclesRequestExample": { "description": "Shared by 2 operations.", "value": { "registration": "CA 123-456", "fleetNumber": "INV-0001", "make": "Toyota", "model": "Hilux 2.4 GD-6", "year": 2026, "vehicleType": "bakkie", "payloadKg": 1.0, "volumeM3": 1.0, "palletCapacity": 1, "odometerKm": 1.0, "fuelType": "standard", "tankLitres": 1.0, "licenceDiscExpiry": "2026-09-30", "roadworthyExpiry": "2026-09-30", "operatorCardExpiry": "2026-09-30", "status": "active", "homeLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fixedAssetId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "telematicsExternalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } }, "PostApiLogisticsVehiclesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registration": "text", "fleetNumber": "INV-0001", "make": "text", "model": "text", "year": 2026, "vehicleType": "bakkie", "payloadKg": 1.0, "volumeM3": 1.0, "palletCapacity": 1, "odometerKm": 1.0, "fuelType": "standard", "tankLitres": 1.0, "licenceDiscExpiry": "2026-09-30", "roadworthyExpiry": "2026-09-30", "operatorCardExpiry": "2026-09-30", "status": "active", "homeLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "homeLocationName": "Karoo Fresh Holdings Ltd", "fixedAssetId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "telematicsExternalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "soonestComplianceExpiryDays": 30, "soonestComplianceExpiryKind": "standard", "onTrip": false, "currentTripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "currentTripNumber": "INV-0001", "lastPosition": { "latitude": 1.0, "longitude": 1.0, "accuracyM": 1.0, "speedKph": 1.0, "headingDeg": 1.0, "recordedAt": "2026-09-01T09:15:00Z", "receivedAt": "2026-09-01T09:15:00Z", "batteryPercent": 15, "source": "driver_app", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ageMinutes": 1 } } }, "PostApiMileageTripsResponseExample": { "description": "Shared by 6 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripDate": "2026-09-01", "origin": "sale", "destination": "accounts@karoofresh.example", "distanceKm": 1.0, "ratePerKm": 1.0, "claimAmount": 10005.0, "purpose": "sale", "vehicle": "CA 123-456", "status": "sent", "createdBy": "Thandi Mokoena", "createdByName": "Thandi Mokoena", "approvedBy": "Thandi Mokoena", "approvedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiMrpCheckPlansResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "4a1e0a00-1111-4222-8333-944455556666", "label": "Cold room temperature", "kind": "measure", "minValue": 0.0, "maxValue": 5.0, "unit": "C", "everyHours": 4, "workCentreId": null, "workCentreCode": null, "active": true } }, "PostApiMrpConvertResponseExample": { "description": "Shared by 2 operations.", "value": { "requisitionIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "requisitionNumbers": [ "INV-0001" ], "workOrderIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "workOrderNumbers": [ "PO-0001" ], "convertedCount": 3, "skipped": [ { "plannedOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year." } ] } }, "PostApiMrpProductionScheduleResponseExample": { "description": "Shared by 2 operations.", "value": { "runId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "runNumber": "MRP-0031", "editable": true, "notEditableReason": null, "today": "2026-09-26", "buckets": [ { "index": 0, "start": "2026-09-26", "end": "2026-10-02", "label": "26 Sep" } ], "rows": [ { "productId": "8c1e2f40-9d3a-4b7e-a1c2-5f6e7d8c9b0a", "sku": "KSW-FG-GATE36", "productName": "Double driveway gate 3.6m", "qtyPrecision": 0, "opening": 4.0, "weeks": [ { "bucketIndex": 0, "start": "2026-09-26", "forecast": 6.0, "firm": 2.0, "demand": 6.0, "receipts": 0.0, "build": 10.0, "scheduled": true } ] } ] } }, "PostApiMrpRoutingsResponseExample": { "description": "Shared by 4 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomName": "Karoo Fresh Holdings Ltd", "name": "Karoo Fresh Holdings Ltd", "version": "1", "status": "sent", "isDefault": true, "expectedYieldPercent": 15.0, "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "notes": "Budget deferred to the next financial year.", "operations": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sequenceNo": 1, "description": "Consulting services — August 2026", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workCentreCode": "CT-001", "workCentreName": "Karoo Fresh Holdings Ltd", "setupHours": 3.0, "runHoursPerUnit": 3.0, "isSubcontract": false, "subcontractSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subcontractSupplierName": "Karoo Fresh Holdings Ltd", "subcontractCostPerUnit": 10005.0, "subcontractLeadDays": 30, "instructions": "Budget deferred to the next financial year.", "hoursForQty": 3.0, "costForQty": 3.0 } ], "qty": 3.0, "startedQty": 3.0, "setupHours": 3.0, "runHours": 3.0, "totalHours": 3.0, "labourCost": 10005.0, "overheadCost": 10005.0, "subcontractCost": 10005.0, "totalCost": 10005.0, "costPerUnit": 10005.0, "unassignedOperationCount": 3 } }, "PostApiMrpRunsResponseExample": { "description": "Shared by 3 operations.", "value": { "run": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "runNumber": "INV-0001", "name": "Karoo Fresh Holdings Ltd", "status": "sent", "horizonStart": "2026-09-01", "horizonEnd": "2026-09-30", "bucketDays": 30, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "includeSafetyStock": true, "includeOnOrder": true, "netOffPlannedOrders": true, "supersedesRunId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "plannedOrderCount": 3, "purchaseOrderCount": 3, "productionOrderCount": 3, "exceptionCount": 3, "demandLineCount": 3, "productCount": 3, "maxLevel": 1, "totalPlannedValue": 10005.0, "unplannedDemandCount": 3, "convertedCount": 3, "durationMs": 1, "errorText": "text", "startedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "createdByName": "Thandi Mokoena", "kind": "standard", "whatIfDemandPercent": 15, "whatIfProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "whatIfProductName": "Karoo Fresh Holdings Ltd", "whatIfExtraLeadDays": 30 }, "plannedOrders": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "runId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "engineKey": "text", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "orderType": "standard", "lowLevelCode": 1, "bucketIndex": 1, "qtyNet": 8700.0, "qtyOrdered": 1.0, "requiredDate": "2026-09-01", "releaseDate": "2026-09-01", "leadTimeDays": 30, "status": "sent", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "unitCost": 2900.0, "estimatedCost": 10005.0, "exceptions": [ "text" ], "requisitionLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "requisitionNumber": "INV-0001", "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workOrderNumber": "PO-0001", "pegging": [ { "demandSource": "referral", "demandRef": "INV-0001", "qty": 3.0, "requiredDate": "2026-09-01", "parentEngineKey": "text", "parentProductName": "Karoo Fresh Holdings Ltd" } ], "onHand": 1.0, "notes": "Budget deferred to the next financial year." } ], "projections": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "lowLevelCode": 1, "sourceType": "invoice", "safetyStock": 1.0, "leadTimeDays": 30, "openingOnHand": 1.0, "cells": [ { "bucketIndex": 1, "bucketStart": "2026-09-01", "bucketEnd": "2026-09-30", "grossRequirement": 1.0, "scheduledReceipts": 1.0, "plannedReceipts": 1.0, "projectedOnHand": 1.0, "netRequirement": 8700.0, "plannedReleases": 1.0, "belowSafety": false } ] } ], "buckets": [ { "index": 1, "start": "2026-09-01", "end": "2026-09-30", "label": "Karoo Fresh Holdings Ltd" } ], "unplannedDemand": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "sourceType": "invoice", "sourceRef": "INV-0001", "qty": 3.0, "requiredDate": "2026-09-01", "bucketIndex": 1, "unplanned": false } ], "cycles": [ [ "text" ] ], "capacity": [ { "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "cells": [ { "bucketIndex": 1, "plannedHours": 3.0, "floorHours": 3.0, "availableHours": 3.0 } ] } ], "supplyActions": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "sku": "LEN-TP-14G4", "source": "referral", "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "action": "created", "currentDate": "2026-09-01", "suggestedDate": "2026-09-01", "qty": 3.0, "suggestedQty": 3.0, "qtyPrecision": 3 } ], "outsideWork": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "sku": "LEN-TP-14G4", "step": "text", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workOrderNumber": "PO-0001", "plannedOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qty": 3.0, "unitCost": 2900.0, "estimatedCost": 10005.0, "releaseDate": "2026-09-01", "requiredDate": "2026-09-01", "leadDays": 30, "status": "sent", "requisitionNumber": "INV-0001", "qtyPrecision": 3 } ] } }, "PostApiMrpWorkCentresResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "kind": "standard", "capacityHoursPerDay": 3.0, "machineCount": 1, "efficiencyPercent": 15.0, "workingDays": [ 30 ], "queueDays": 30, "labourRatePerHour": 1.0, "overheadRatePerHour": 1.0, "isSubcontract": false, "observePublicHolidays": true, "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "active": true, "notes": "Budget deferred to the next financial year.", "dailyEffectiveHours": 3.0, "routingOperationCount": 3, "openOperationCount": 3 } }, "PostApiPayrollBeneficiariesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "beneficiaryType": "standard", "typeLabel": "Standard", "accountReference": "INV-0001", "bankName": "FNB", "bankAccountNumber": "62012345678", "bankBranchCode": "250655", "contactEmail": "accounts@karoofresh.example", "contactPhone": "+27 82 555 0143", "remittanceEmail": "accounts@karoofresh.example", "notes": "Budget deferred to the next financial year.", "isActive": true, "memberCount": 3 } }, "PostApiPayrollDeductionsRequestExample": { "description": "Shared by 2 operations.", "value": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "beneficiaryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "memberReference": "INV-0001", "calculation": "fixed", "employeeAmount": 10005.0, "employerAmount": 10005.0, "employeePercent": 15.0, "employerPercent": 15.0, "totalOwing": 10005.0, "orderReference": "INV-0001", "startDate": "2026-09-01", "endDate": "2026-09-30", "isActive": true, "notes": "Budget deferred to the next financial year.", "s34AgreementDocumentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "s34FaultConfirmed": false, "s34ProcedureDate": "2026-09-01", "s34ActualLoss": 1.0, "consentDate": "2026-02-20", "consentReference": "Signed loan agreement, personnel file", "isFine": false } }, "PostApiPayrollDeductionsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "beneficiaryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "beneficiaryName": "Karoo Fresh Holdings Ltd", "beneficiaryType": "standard", "memberReference": "INV-0001", "calculation": "fixed", "employeeAmount": 10005.0, "employerAmount": 10005.0, "employeePercent": 15.0, "employerPercent": 15.0, "totalOwing": 10005.0, "totalPaid": 10005.0, "outstanding": 1.0, "orderReference": "INV-0001", "startDate": "2026-09-01", "endDate": "2026-09-30", "isActive": true, "notes": "Budget deferred to the next financial year.", "s34AgreementDocumentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "s34FaultConfirmed": false, "s34ProcedureDate": "2026-09-01", "s34ActualLoss": 1.0, "consentDate": "2026-02-20", "consentReference": "Signed loan agreement, personnel file", "packageNotice": "This run includes a catch-up deduction; the year-to-date total is correct." } }, "PostApiPayrollEarningTypesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "sarsCode": "CT-001", "sarsLabel": "Karoo Fresh Holdings Ltd", "calculation": "text", "calculationLabel": "Karoo Fresh Holdings Ltd", "defaultAmount": 10005.0, "defaultPercent": 15.0, "defaultRate": 15.0, "unitLabel": "Karoo Fresh Holdings Ltd", "active": true, "sortOrder": 1, "notes": "Budget deferred to the next financial year.", "taxable": true, "assignedCount": 3, "glAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "postsToLabel": "Karoo Fresh Holdings Ltd", "postsToIsDefault": true, "problem": "text" } }, "PostApiPayrollFringeBenefitsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "benefitType": "COMPANY_CAR", "typeLabel": "Company car", "description": "Consulting services — August 2026", "determinedValue": 10005.0, "maintenancePlanIncluded": false, "inputTaxClaimed": false, "employeeBearsMaintenance": false, "depreciationYears": 1, "operatingLeaseCost": 10005.0, "operatingLeaseFuelCost": 10005.0, "businessUseAtLeast80": false, "employeeConsideration": 1.0, "loanBalance": 10005.0, "loanInterestPaid": 1.0, "repoRate": 15.0, "remunerationProxy": 1.0, "abatementNil": false, "atLeastFourRooms": false, "furnished": false, "powerOrFuelSupplied": false, "employerExpenditure": 1.0, "employeeRent": 1.0, "monthlyAmount": 10005.0, "noValueProvision": false, "noValueReason": "Budget deferred to the next financial year.", "startDate": "2026-09-01", "endDate": "2026-09-30", "isActive": true, "notes": "Budget deferred to the next financial year.", "monthlyValue": 10005.0, "monthlyRemuneration": 1.0, "sourceCode": "CT-001", "workings": "text", "issue": "The control account and the age analysis differ by R0.00.", "used": false } }, "PostApiPayrollPayTemplatesByIdRatesResponseExample": { "description": "Shared by 3 operations.", "value": { "employees": 6, "overriddenBy": [ "Guard6 Scope" ], "sentence": "This reaches 5 employees on the template; 1 employee keep their own figure (Guard6 Scope)." } }, "PostApiPayrollPayTemplatesRequestExample": { "description": "Shared by 2 operations.", "value": { "name": "Karoo Fresh Holdings Ltd", "payBasis": "monthly", "ordinaryHoursWeekly": 3.0, "ordinaryDaysWeekly": 30, "ordinarilyWorksSundays": false, "shiftHours": 3.0, "dayCapHours": 3.0, "fundSalaryWeeklyHours": 3.0, "fundSalaryWeeks": 1.0, "council": "NBCPSS", "councilGrade": "C", "councilArea": "1" } }, "PostApiPayrollPayTemplatesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "payBasis": "invoice", "ordinaryHoursWeekly": 3.0, "ordinaryDaysWeekly": 30, "ordinarilyWorksSundays": false, "shiftHours": 3.0, "dayCapHours": 3.0, "fundSalaryWeeklyHours": 3.0, "fundSalaryWeeks": 1.0, "agreements": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "templateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "startsOn": "2026-09-01", "endsOn": "2026-09-01", "averageWeeklyHours": 3.0, "overtimeWeeklyCap": 1.0 } ], "rates": [ { "effectiveFrom": "2026-09-01", "monthlySalary": 1.0, "hourlyRate": 15.0 } ], "earnings": [ { "earningTypeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeName": "Overtime", "effectiveFrom": "2026-09-01", "amount": 10005.0, "percent": 15.0, "rate": 15.0, "units": 1.0 } ], "deductions": [ { "beneficiaryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "beneficiaryName": "Highveld Provident Fund", "effectiveFrom": "2026-09-01", "base": "text", "calculation": "text", "employeeAmount": 10005.0, "employerAmount": 10005.0, "employeePercent": 15.0, "employerPercent": 15.0, "unpaidLeave": "follows_base" } ], "employeeCount": 3 } }, "PostApiPayrollPeriodsResponseExample": { "description": "Shared by 6 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodType": "2026-09", "startDate": "2026-09-01", "endDate": "2026-09-30", "payDate": "2026-09-01", "status": "sent", "grossTotal": 10005.0, "payeTotal": 10005.0, "uifTotal": 10005.0, "sdlTotal": 10005.0, "nettTotal": 8700.0, "employeeCount": 3, "uifEmployeeTotal": 10005.0, "uifEmployerTotal": 10005.0, "pensionTotal": 10005.0, "medicalTotal": 10005.0, "thirdPartyDeductionsTotal": 10005.0, "employerRetirementTotal": 10005.0, "employerMedicalTotal": 10005.0, "employeeDeductionsTotal": 10005.0, "employerContributionsTotal": 10005.0, "costToCompanyTotal": 10005.0, "deductionsReconcile": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiPerDiemClaimsResponseExample": { "description": "Shared by 5 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employee": "Thandi Mokoena", "destination": "accounts@karoofresh.example", "periodLabel": "2026-09", "days": 30, "ratePerDay": 1.0, "totalAmount": 10005.0, "policy": "fifo", "status": "sent", "rejectionReason": "Budget deferred to the next financial year.", "createdBy": "Thandi Mokoena", "createdByName": "Thandi Mokoena", "approvedBy": "Thandi Mokoena", "approvedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiPettyCashTxnsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "category": "Office supplies", "receipt": false, "createdBy": "Thandi Mokoena", "createdByName": "Thandi Mokoena", "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiPosJournalsResponseExample": { "description": "Shared by 2 operations.", "value": { "clientId": "6f1d2c7a-3b4e-3c5d-9e8f-0a1b2c3d4e5f", "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "sales", "journalDate": "2026-10-01", "reference": "ruva:day:loc-main:2026-10-01:r1", "standardRatedNetCents": 99565, "zeroRatedCents": 0, "outputVatCents": 14935, "inputVatCents": 0, "costOfSalesCents": 0 } }, "PostApiPractitionerClientsByIdAddonsResponseExample": { "description": "Shared by 2 operations.", "value": { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "addonId": "job-cards", "quantity": 3, "addonCentsMonthly": 49900, "proratedCentsNow": 49900, "notice": "This run includes a catch-up deduction; the year-to-date total is correct." } }, "PostApiPractitionerLinksResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "practitionerEmail": "accounts@karoofresh.example", "practitionerName": "Karoo Fresh Holdings Ltd", "status": "sent", "accessLevel": "text", "invitedAt": "2026-09-01T09:15:00Z", "acceptedAt": "2026-09-01T09:15:00Z" } }, "PostApiPractitionerQueriesResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subjectType": "standard", "subjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subjectLabel": "Karoo Fresh Holdings Ltd", "question": "text", "status": "sent", "priority": "normal", "answer": "text", "askedByEmail": "accounts@karoofresh.example", "createdAt": "2026-09-01T09:15:00Z", "answeredAt": "2026-09-01T09:15:00Z", "resolvedAt": "2026-09-01T09:15:00Z" } }, "PostApiProcurementMatchesByBillIdResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billNumber": "INV-0001", "vendorName": "Karoo Fresh Holdings Ltd", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "goodsReceiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "goodsReceiptNumber": "INV-0001", "status": "sent", "poTotal": 10005.0, "receiptTotal": 10005.0, "invoiceTotal": 10005.0, "priceVariance": 10005.0, "priceVariancePercent": 15.0, "qtyVariance": 1.0, "toleranceAmount": 10005.0, "tolerancePercent": 15.0, "lines": [ { "description": "Consulting services — August 2026", "qtyOrdered": 1.0, "qtyReceived": 1.0, "qtyBilled": 1.0, "lineMatched": false, "priceOrdered": 10005.0, "priceReceived": 10005.0, "priceVariance": 10005.0, "qtyVariance": 1.0, "withinTolerance": true, "note": "Budget deferred to the next financial year." } ], "matchedAt": "2026-09-01T09:15:00Z", "resolvedAt": "2026-09-01T09:15:00Z", "resolvedByName": "Karoo Fresh Holdings Ltd", "resolutionNote": "Budget deferred to the next financial year.", "blocksPayment": false, "matchBasis": "invoice", "overBilledQty": 3.0 } }, "PostApiPropertySalesResponseExample": { "description": "Shared by 4 operations.", "value": { "id": "7f6c1a2e-0000-4000-8000-000000000020", "property": "Erf 412, Stellenbosch", "buyer": "T Mokoena", "agreementDate": "2026-08-01", "price": 1150000.0, "treatment": "vat", "treatmentNote": "A taxable supply by a VAT vendor: VAT is charged and the buyer pays no transfer duty (Transfer Duty Act s9(15)).", "heldAs": "stock", "fixedAssetId": null, "capitalGoods": false, "residentialPriceFixed": false, "timeOfSupply": "2026-08-15", "ratePercent": 15.0, "rateReason": "s9(3)(d): the rate on the time of supply", "registeredOn": null, "payments": [ { "id": "7f6c1a2e-0000-4000-8000-000000000021", "paidOn": "2026-08-15", "amount": 115000.0, "heldInTrust": false, "declaredOn": "2026-08-15", "vatAmount": 15000.0 } ], "received": 115000.0, "vatDeclared": 15000.0 } }, "PostApiRecurringResponseExample": { "description": "Shared by 4 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "amount": 10005.0, "frequency": "monthly", "nextDate": "2026-09-01", "active": true, "currency": "ZAR", "documentType": "invoice", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "onCreate": "email" } }, "PostApiRentalContractsByIdReturnResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contractNumber": "INV-0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "site": "text", "status": "sent", "outDate": "2026-09-01", "dueBack": "text", "offHiredOn": "2026-09-01", "delivery": false, "collection": false, "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hireItemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "kind": "standard", "quantity": 3, "qtyOut": 3, "qtyBack": 3, "qtyMissing": 3, "withCustomer": 1, "toGo": 1, "offHiredOn": "2026-09-01", "hireCharge": 1.0, "periods": "2026-09" } ], "charges": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "description": "Consulting services — August 2026", "quantity": 1, "unitAmount": 10005.0, "total": 10005.0 } ], "stops": [ { "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "stopType": "standard", "status": "sent", "hasProof": false } ], "photoCount": 3, "total": 10005.0 } }, "PostApiRentalItemsResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fixedAssetId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "assetNumber": "INV-0001", "name": "Karoo Fresh Holdings Ltd", "itemClass": "text", "kind": "standard", "quantity": 3, "available": 1, "reserved": 1, "onHire": 1, "inService": 1, "lost": 1, "status": "sent" } }, "PostApiRentedLeasesRequestExample": { "description": "Shared by 2 operations.", "value": { "contactId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "description": "Head office, 12 Main Street", "startDate": "2026-03-01", "endDate": "2029-02-28", "intervalMonths": 1, "rent": 10000.0, "escalationPercent": 10.0, "escalationDate": "2027-03-01", "escalationMonths": 12 } }, "PostApiRentedLeasesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "contactId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "contactName": "Karoo Properties", "description": "Head office, 12 Main Street", "startDate": "2026-03-01", "endDate": "2029-02-28", "intervalMonths": 1, "rent": 10000.0, "escalationPercent": 10.0, "escalationDate": "2027-03-01", "escalationMonths": 12, "levelRent": 11033.33, "cycles": 36, "bills": 12, "billed": 120000.0, "expensed": 132399.96, "accrued": 12399.96, "kind": "operating", "loanId": null, "fixedAssetId": null } }, "PostApiReportPacksResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Board pack", "coverTitle": "Monthly board pack", "commentary": "A strong month.", "reports": [ "income", "balance", "ageddebtors" ], "period": "last_month" } }, "PostApiReportsCustomRequestExample": { "description": "Shared by 3 operations.", "value": { "name": "Margin by customer", "periodGrouping": "quarter", "dimensions": [ "customer", "costCentre" ], "measures": [ "revenue", "costOfSales", "grossProfit", "grossMargin", "netProfit" ], "filters": { "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "sections": [ "revenue" ] } } }, "PostApiReportsCustomResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "definition": { "name": "Karoo Fresh Holdings Ltd", "periodGrouping": "2026-09", "dimensions": [ "text" ], "measures": [ "text" ], "filters": { "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "sections": [ "text" ] } }, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiReportsCustomRunResponseExample": { "description": "Shared by 2 operations.", "value": { "name": "Karoo Fresh Holdings Ltd", "periodLabel": "2026-09", "from": "2026-09-01", "to": "2026-09-30", "columns": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd", "kind": "standard" } ], "rows": [ { "labels": [ "Karoo Fresh Holdings Ltd" ], "values": [ 10005.0 ] } ], "totals": [ 10005.0 ], "reconciles": true, "filtered": true, "companies": [ "text" ] } }, "PostApiReportsScheduledResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "reportType": "income", "frequency": "monthly", "nextRun": "text", "recipients": "text", "format": "CSV", "active": true, "lastRun": "text", "lastStatus": "text" } }, "PostApiRolesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "isSystem": false, "permissions": [ { "resource": "invoices", "action": "created" } ], "userCount": 3, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiSarsIrp6SubmitResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "submissionType": "EMP201", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "totalPaye": 12400.0, "totalUif": 1062.72, "totalSdl": 890.0, "totalEti": 500.0, "totalPayable": 13852.72, "totalDue": 13852.72, "status": "sent", "referenceNumber": "INV-0001", "submittedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z" } }, "PostApiSarsSubmissionsResponseExample": { "description": "Shared by 5 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "submissionType": "EMP201", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "totalPaye": 12400.0, "totalUif": 1062.72, "totalSdl": 890.0, "totalEti": 500.0, "totalPayable": 13852.72, "totalDue": 13852.72, "status": "sent", "referenceNumber": "INV-0001", "paymentReferenceNumber": "7012345676LC2609000", "submittedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z" } }, "PostApiWorkOrdersByIdReworkStepResponseExample": { "description": "Shared by 2 operations.", "value": { "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "status": "sent", "productName": "Karoo Fresh Holdings Ltd", "routingId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "routingName": "Karoo Fresh Holdings Ltd", "expectedYieldPercent": 15.0, "qtyPlanned": 1.0, "qtyToStart": 1.0, "qtyCompleted": 1.0, "qtyScrapped": 1.0, "operations": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "routingOperationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sequenceNo": 1, "description": "Consulting services — August 2026", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workCentreCode": "CT-001", "workCentreName": "Karoo Fresh Holdings Ltd", "status": "sent", "plannedSetupHours": 3.0, "plannedRunHours": 3.0, "plannedHours": 3.0, "actualHours": 3.0, "varianceHours": 3.0, "qtyCompleted": 1.0, "qtyScrapped": 1.0, "labourRatePerHour": 1.0, "overheadRatePerHour": 1.0, "actualCost": 10005.0, "plannedCost": 10005.0, "isSubcontract": false, "subcontractSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subcontractSupplierName": "Karoo Fresh Holdings Ltd", "scheduledStart": "2026-09-01", "scheduledFinish": "text", "startedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "operatorName": "Karoo Fresh Holdings Ltd", "notes": "Budget deferred to the next financial year." } ], "operationCount": 3, "completedOperationCount": 3, "percentComplete": 15.0, "plannedHours": 3.0, "actualHours": 3.0, "varianceHours": 3.0, "actualLabourCost": 10005.0, "currentOperation": "text", "holds": [] } }, "PostApiWorkflowsBoardsResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "keyPrefix": "INV-", "description": "Consulting services — August 2026", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectName": "Karoo Fresh Holdings Ltd", "archived": false, "columns": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "stage": "text", "position": 1, "wipLimit": 50, "count": 3 } ], "itemCount": 3, "openCount": 3, "createdAt": "2026-09-01T09:15:00Z" } }, "PostApiWorkflowsItemsResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "boardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "columnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stage": "text", "columnName": "Karoo Fresh Holdings Ltd", "itemKey": "text", "title": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "itemType": "standard", "priority": "normal", "labels": [ "Karoo Fresh Holdings Ltd" ], "assigneeUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "assigneeName": "Thandi Mokoena", "reporterUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reporterName": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectName": "Karoo Fresh Holdings Ltd", "estimateMinutes": 1, "loggedMinutes": 1, "dueDate": "2026-09-01", "rank": 1.0, "startedAt": "2026-09-01T09:15:00Z", "closedAt": "2026-09-01T09:15:00Z", "commentCount": 3, "attachmentCount": 3, "recurrenceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "recurrenceName": "Karoo Fresh Holdings Ltd", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PostApiWorkflowsRecurrencesResponseExample": { "description": "Shared by 3 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "boardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "boardName": "Karoo Fresh Holdings Ltd", "name": "Karoo Fresh Holdings Ltd", "cadence": "text", "cadenceLabel": "Karoo Fresh Holdings Ltd", "anchorDate": "2026-09-01", "endsOn": "2026-09-01", "active": true, "columnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "columnName": "Karoo Fresh Holdings Ltd", "lastRaisedOn": "2026-09-01", "nextDueLabel": "Karoo Fresh Holdings Ltd", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "title": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "itemType": "standard", "priority": "normal", "labels": [ "Karoo Fresh Holdings Ltd" ], "assigneeUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "assigneeName": "Thandi Mokoena", "estimateMinutes": 1, "dueOffsetDays": 30, "position": 1 } ] } }, "PostDriverApiV1FuelRequestExample": { "description": "Shared by 2 operations.", "value": { "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "filledOn": "2026-09-01", "litres": 62.4, "amount": 1310.4, "odometerKm": 184320.0, "garage": "Rivonia Road service station", "cardRef": "FC-4471", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientReference": "0b9e4d2a-7c31-4f58-a6e0-5d2c8f1b3e47" } }, "PostDriverApiV1FuelResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "filledOn": "2026-09-01", "litres": 1.0, "amount": 10005.0, "odometerKm": 1.0, "garage": "text", "cardRef": "INV-0001", "source": "office", "expenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } }, "PostDriverApiV1StopsByIdProofRequestExample": { "description": "Shared by 2 operations.", "value": { "returnables": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "out": 10, "back": 8 } ], "temperatures": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "celsius": 4.0 } ], "outcome": "Interested — sending a quote on Friday", "receivedByName": "Karoo Fresh Holdings Ltd", "receivedByRole": "Accountant", "receivedByIdNumber": "INV-0001", "signatureBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "notes": "Budget deferred to the next financial year.", "capturedLatitude": 1.0, "capturedLongitude": 1.0, "capturedAccuracyM": 1.0, "capturedAt": "2026-09-01T09:15:00Z", "deviceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "exceptionReasonCode": "CT-001", "lines": [ { "stopLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyDelivered": 1.0, "qtyReturned": 1.0, "batchNumber": "INV-0001", "notes": "Budget deferred to the next financial year." } ], "clientReference": "INV-0001", "collected": { "amount": 10005.0, "method": "cash", "reference": "INV-0001" } } }, "PostDriverApiV1StopsByIdProofResponseExample": { "description": "Shared by 4 operations.", "value": { "ok": true, "stop": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sequence": 1, "stopType": "standard", "status": "sent", "customerName": "Karoo Fresh Holdings Ltd", "documentNumber": "INV-0001", "address": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "latitude": 1.0, "longitude": 1.0, "contactName": "Karoo Fresh Holdings Ltd", "contactPhone": "+27 82 555 0143", "instructions": "Budget deferred to the next financial year.", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "arrivedAt": "2026-09-01T09:15:00Z", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyOrdered": 1.0, "qtyDelivered": 1.0, "uom": "each", "batchNumber": "INV-0001", "productBarcode": "6001234567890", "qtyLoaded": 1.0, "service": false } ], "hasProof": false, "collectable": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "amountDue": 10005.0, "foreignCurrency": "ZAR" }, "collection": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "paymentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 10005.0, "method": "cash", "reference": "INV-0001", "collectedAt": "2026-09-01T09:15:00Z", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "bankedAt": "2026-09-01T09:15:00Z", "bankingId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } }, "tripStatus": "sent", "serverTime": "2026-09-01T09:15:00Z", "duplicateOfExistingProof": false, "weaknesses": [ "text" ], "strength": "STRONG" } }, "PostDriverApiV1TripsByIdMessagesResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sender": "office", "senderName": "Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached.", "photoUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "clientSeq": 1, "writtenAt": "2026-09-01T09:15:00Z", "deliveredAt": "2026-09-01T09:15:00Z", "readAt": "2026-09-01T09:15:00Z" } }, "PostSupplierApiV1OffersResponseExample": { "description": "Shared by 10 operations.", "value": { "ok": true, "message": "Saved.", "order": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "orderNumber": "PO-0001", "issueDate": "2026-09-01", "expectedDate": "2026-09-01", "status": "sent", "currency": "ZAR", "subtotal": 8700.0, "vatTotal": 1305.0, "total": 10005.0, "deliveryAddress": "12 Long Street, Cape Town, 8001", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "productCode": "CT-001", "quantity": 3.0, "qtyReceived": 1.0, "unitPrice": 2900.0, "vatRate": 15.0, "lineTotal": 10005.0 } ], "acknowledgedAt": "2026-09-01T09:15:00Z", "acknowledgedBy": "text", "ackStatus": "sent", "promisedDate": "2026-09-01", "ackNote": "Budget deferred to the next financial year.", "canAcknowledge": false, "canInvoice": false, "submittedInvoices": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "net": 8700.0, "vat": 1305.0, "gross": 1.0, "currency": "ZAR", "status": "sent", "submittedAt": "2026-09-01T09:15:00Z", "orderNumber": "PO-0001", "lines": [ { "description": "Consulting services — August 2026", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "lineTotal": 10005.0, "vatAmount": 1305.0 } ], "canWithdraw": false, "matchStatus": "sent", "matchNote": "Budget deferred to the next financial year." } ] }, "invoice": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "net": 8700.0, "vat": 1305.0, "gross": 1.0, "currency": "ZAR", "status": "sent", "submittedAt": "2026-09-01T09:15:00Z", "orderNumber": "PO-0001", "lines": [ { "description": "Consulting services — August 2026", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "lineTotal": 10005.0, "vatAmount": 1305.0 } ], "canWithdraw": false, "matchStatus": "sent", "matchNote": "Budget deferred to the next financial year." }, "rfq": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rfqNumber": "INV-0001", "title": "Karoo Fresh Holdings Ltd", "issueDate": "2026-09-01", "responseDueDate": "2026-09-01", "currency": "ZAR", "deliveryAddress": "12 Long Street, Cape Town, 8001", "terms": "Goods remain the property of the seller until paid in full.", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "quantity": 3.0, "unit": "each", "requiredDate": "2026-09-01" } ], "invitationStatus": "sent", "canQuote": false, "submittedQuote": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quoteNumber": "INV-0001", "quoteDate": "2026-09-01", "validUntil": "2026-09-30", "currency": "ZAR", "subtotal": 8700.0, "vatAmount": 1305.0, "total": 10005.0, "leadTimeDays": 30, "paymentTermsDays": 30, "status": "sent", "notes": "Budget deferred to the next financial year.", "lines": [ { "rfqLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "leadTimeDays": 30, "notes": "Budget deferred to the next financial year.", "lineTotal": 10005.0 } ] } } } }, "PutApiCrmActivitiesByIdResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "activityType": "standard", "subject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached.", "dueDate": "2026-09-01", "completedAt": "2026-09-01T09:15:00Z", "isOverdue": false, "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leadName": "Karoo Fresh Holdings Ltd", "opportunityId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "opportunityName": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "outcome": "text", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "PutApiLedgerPeriodsByIdReviewResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "label": "Karoo Fresh Holdings Ltd", "status": "sent", "closedAt": "2026-09-01T09:15:00Z", "reviewedAt": "2026-09-01T09:15:00Z", "reviewedBy": "Karoo Fresh Holdings Ltd", "closedByFirm": false } }, "PutApiLogisticsStopsByIdLocationResponseExample": { "description": "Shared by 2 operations.", "value": { "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "latitude": 1.0, "longitude": 1.0, "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "contactLocationSource": "referral" } }, "PutApiLogisticsStopsByIdRequestExample": { "description": "Shared by 2 operations.", "value": { "linkedCollectionStopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopType": "delivery", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stockLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "address": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "latitude": 1.0, "longitude": 1.0, "contactName": "Karoo Fresh Holdings Ltd", "contactPhone": "+27 82 555 0143", "instructions": "Budget deferred to the next financial year.", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyOrdered": 1.0, "uom": "each", "notes": "Budget deferred to the next financial year." } ], "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hireContractId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } }, "PutApiSecurityPolicyRequestExample": { "description": "Shared by 2 operations.", "value": { "sessionTimeoutMins": 60, "passwordMinLength": 8, "passwordRequireUpper": true, "passwordRequireDigit": true, "passwordRequireSpecial": false, "lockoutMaxAttempts": 5, "lockoutWindowMins": 15, "require2faForAdmins": false, "require2faForEveryone": false, "retentionDays": 2555, "retentionFloorDays": 2555, "retentionNote": null, "maxDevicesPerUser": 3 } } }, "responses": { "Unauthorized": { "description": "Missing, malformed or expired access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The token is valid but the call is not permitted. `MODULE_NOT_LICENSED` — the tenant's plan does not include this module. `INSUFFICIENT_SCOPE` — the API key lacks the named scope. `LICENSE_EXPIRED` — reads still work, writes do not.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "The key exceeded its per-minute ceiling. `Retry-After` gives the seconds until the window rolls; `X-RateLimit-*` headers are on every response, not only this one.", "headers": { "Retry-After": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "Exchange email and password for a JWT. A TOTP code and a recovery code go in the same field — they are told apart by shape, six digits against Crockford Base32 ABCDE-FGHJK.", "operationId": "postAuthLogin", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" }, "totpCode": { "type": "string" }, "deviceId": { "type": "string" }, "devicePlatform": { "type": "string" } } }, "example": { "email": "you@example.example", "password": "your-password", "totpCode": "123456", "deviceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "devicePlatform": "android" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "userId": { "type": "string" }, "tenantId": { "type": "string" }, "tenantName": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "mustEnroll2fa": { "type": "boolean" }, "mustChangePassword": { "type": "boolean" } } }, "example": { "accessToken": "", "refreshToken": "", "userId": "05aea44f-e1a0-5fc5-a870-df0697216af5", "tenantId": "f80b8d0f-4c0f-58e9-80a4-5915fa569c52", "tenantName": "Your Business", "email": "you@example.example", "role": "owner", "firstName": "Thandi", "lastName": "Mokoena", "mustEnroll2fa": false, "mustChangePassword": false } } } } } } }, "/auth/refresh": { "post": { "tags": [ "Authentication" ], "summary": "Exchange a refresh token for a new access token.", "operationId": "postAuthRefresh", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string" } } }, "example": { "refreshToken": "" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "userId": { "type": "string" }, "tenantId": { "type": "string" }, "tenantName": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "entitlements": { "$ref": "#/components/schemas/GetApiTenantEntitlementsResponse" }, "mustEnroll2fa": { "type": "boolean" }, "mustChangePassword": { "type": "boolean" } } }, "example": { "accessToken": "", "refreshToken": "", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantName": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "role": "Accountant", "firstName": "Karoo Fresh Holdings Ltd", "lastName": "Karoo Fresh Holdings Ltd", "entitlements": { "plan": "business", "planDisplayName": "Karoo Fresh Holdings Ltd", "maxUsers": 1, "licenseValidUntil": "2026-09-30", "modules": [ "invoices" ], "expired": false, "activeUsers": 1, "invoicesThisMonth": 9, "invoiceLimit": 50, "payrollEmployees": 1, "payrollBand": "1 to 10 employees", "payrollBandLicensed": "1 to 10 employees", "payrollBandMonthly": 1.0, "payrollBandExceeded": false, "payrollBandHeadroom": 1, "payrollBandSummary": "Consulting services — August 2026", "storageUsedBytes": 1, "storageUsedGb": 1, "storageIncludedGb": 1, "storageExtraGb": 1, "storageMonthlyUplift": 1.0, "storageExceedsLicensed": false, "storageHeadroomGb": 1, "storageSummary": "Consulting services — August 2026", "whatsAppUsed": 1, "whatsAppIncluded": 1, "whatsAppExtra": 1, "whatsAppMonthlyUplift": 1.0, "whatsAppHeadroom": 1, "whatsAppSummary": "Consulting services — August 2026", "scanUsed": 1, "scanIncluded": 1, "scanExtra": 1, "scanMonthlyUplift": 1.0, "scanHeadroom": 1, "aiAssist": false, "scanSummary": "Consulting services — August 2026", "practiceClients": 1, "practicePaidClients": 1, "practiceStatus": "sent", "practiceStatusName": "Karoo Fresh Holdings Ltd", "practicePayoutPercent": 0.0, "practiceMonthlyPayout": 1.0, "practiceClientsToNextStatus": 1, "practiceSummary": "Consulting services — August 2026", "planIncludedUsers": 1, "companies": 1, "maxCompanies": 1, "planIncludedCompanies": 1, "companiesSummary": "Consulting services — August 2026", "addons": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "displayName": "Karoo Fresh Holdings Ltd", "blurb": "Budget deferred to the next financial year.", "unitPriceMonthly": 2900.0, "quantity": 3, "monthlyPrice": 10005.0, "seatsPerUnit": 1, "unlocks": [ "text" ], "maxQuantity": 3, "unitLabel": "Karoo Fresh Holdings Ltd" } ], "availableAddons": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "displayName": "Karoo Fresh Holdings Ltd", "blurb": "Budget deferred to the next financial year.", "unitPriceMonthly": 2900.0, "quantity": 3, "monthlyPrice": 10005.0, "seatsPerUnit": 1, "unlocks": [ "text" ], "maxQuantity": 3, "unitLabel": "Karoo Fresh Holdings Ltd" } ], "addonsMonthlyTotal": 10005.0, "addonUpgradeSuggestion": "The Business plan costs less than your current add-ons.", "apiKeysUsed": 1, "apiKeysIncluded": 1, "apiKeysHeadroom": 1, "apiKeysSummary": "Consulting services — August 2026" }, "mustEnroll2fa": false, "mustChangePassword": false } } } } } } }, "/auth/logout": { "post": { "tags": [ "Authentication" ], "summary": "Revoke the current session. The token stops working on the next request rather than when it expires.", "operationId": "postAuthLogout", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthLogoutResponse" }, "example": { "message": "Signed out." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/auth/me": { "get": { "tags": [ "Authentication" ], "summary": "The signed-in user, their tenant, their roles and the company they are acting in.", "operationId": "getAuthMe", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "tenantId": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" } } }, "example": { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "email": "accounts@karoofresh.example", "role": "Accountant" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/auth/token": { "post": { "tags": [ "Authentication" ], "summary": "Exchange an API key for a short-lived access token.", "operationId": "postAuthToken", "description": "Send the API key as a bearer credential; receive a one-hour access token carrying the key's scopes. This is how an integration authenticates — it never needs, and must never be given, a user's password. The token is an ordinary access token, so every endpoint below accepts it unchanged.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "A token, its lifetime, the granted scopes and the key's rate limit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string" }, "tokenType": { "type": "string" }, "expiresIn": { "type": "integer" }, "scope": { "type": "string" }, "tenantId": { "type": "string", "format": "uuid" }, "rateLimitPerMinute": { "type": "integer" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/oauth/authorize": { "get": { "tags": [ "Authentication" ], "summary": "OAuth 2: send a person here to connect your app. They sign in on Ledgr's own page, see the scopes you asked for, may untick any, and are returned to your registered redirect with ?code=&state= (or ?error=access_denied). Optional PKCE: code_challenge with code_challenge_method=S256.", "operationId": "getOauthAuthorize", "security": [], "parameters": [ { "name": "response_type", "in": "query", "required": false, "schema": { "type": "string" }, "example": "code" }, { "name": "client_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "{clientId}" }, { "name": "redirect_uri", "in": "query", "required": false, "schema": { "type": "string" }, "example": "{uri}" }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" }, "example": "{scopes}" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "example": "{state}" } ], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Authentication" ], "summary": "The consent page's own form (the person's sign-in and the scopes they ticked). Not called by an app.", "operationId": "postOauthAuthorize", "security": [], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } } } } }, "/oauth/token": { "post": { "tags": [ "Authentication" ], "summary": "OAuth 2 token exchange, form-encoded, with the app's client_id and client_secret (in the form or as HTTP Basic). grant_type=authorization_code with code and redirect_uri (and code_verifier when a challenge was sent) returns an access token and a refresh token; grant_type=refresh_token returns a new access token. The token acts as the person who connected the app, with only the scopes they granted.", "operationId": "postOauthToken", "security": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" }, "tenant_id": { "type": "string" } } }, "example": { "access_token": "", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "ledgr_… (keep it secret, with your client secret)", "scope": "invoices:read", "tenant_id": "751f8fc2-155d-50b1-a7e9-eb46ba03ebca" } } } } } } }, "/api-scopes": { "get": { "tags": [ "Authentication" ], "summary": "List every scope an API key can hold.", "operationId": "getApiScopes", "description": "Public and unauthenticated, so tooling can render the scope picker without a key.", "security": [], "responses": { "200": { "description": "The scope catalogue." } } } }, "/auth/verify-email/resend": { "post": { "tags": [ "Authentication" ], "summary": "Send the signed-in user another verification email. Five an hour per address.", "operationId": "postAuthVerifyEmailResend", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "sent": { "type": "boolean" } } }, "example": { "verified": false, "sent": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/users/{id}/2fa/reset": { "post": { "tags": [ "Two-factor authentication" ], "summary": "Clear ANOTHER user's 2FA after a lost phone. Needs roles:edit plus an owner or admin role, refuses id == self, revokes the target's sessions, audits at warning and emails them.", "operationId": "postApiUsersById2faReset", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "123456" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "hadEnrolledFactor": { "type": "boolean" }, "recoveryCodesRevoked": { "type": "integer" }, "userNotified": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "email": "accounts@karoofresh.example", "hadEnrolledFactor": true, "recoveryCodesRevoked": 1, "userNotified": true, "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/tenant/entitlements": { "get": { "tags": [ "Tenant, plan & entitlements" ], "summary": "The plan, its modules, seat and storage allowances, live usage against them, and the licence's expiry. The client calls this at app start and from its nav guard.", "operationId": "getApiTenantEntitlements", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiTenantEntitlementsResponse" }, "example": { "plan": "business", "planDisplayName": "Karoo Fresh Holdings Ltd", "maxUsers": 1, "licenseValidUntil": "2026-09-30", "modules": [ "invoices" ], "expired": false, "activeUsers": 1, "invoicesThisMonth": 9, "invoiceLimit": 50, "payrollEmployees": 1, "payrollBand": "1 to 10 employees", "payrollBandLicensed": "1 to 10 employees", "payrollBandMonthly": 1.0, "payrollBandExceeded": false, "payrollBandHeadroom": 1, "payrollBandSummary": "Consulting services — August 2026", "storageUsedBytes": 1, "storageUsedGb": 1, "storageIncludedGb": 1, "storageExtraGb": 1, "storageMonthlyUplift": 1.0, "storageExceedsLicensed": false, "storageHeadroomGb": 1, "storageSummary": "Consulting services — August 2026", "whatsAppUsed": 1, "whatsAppIncluded": 1, "whatsAppExtra": 1, "whatsAppMonthlyUplift": 1.0, "whatsAppHeadroom": 1, "whatsAppSummary": "Consulting services — August 2026", "scanUsed": 1, "scanIncluded": 1, "scanExtra": 1, "scanMonthlyUplift": 1.0, "scanHeadroom": 1, "aiAssist": false, "scanSummary": "Consulting services — August 2026", "practiceClients": 1, "practicePaidClients": 1, "practiceStatus": "sent", "practiceStatusName": "Karoo Fresh Holdings Ltd", "practicePayoutPercent": 0.0, "practiceMonthlyPayout": 1.0, "practiceClientsToNextStatus": 1, "practiceSummary": "Consulting services — August 2026", "planIncludedUsers": 1, "companies": 1, "maxCompanies": 1, "planIncludedCompanies": 1, "companiesSummary": "Consulting services — August 2026", "addons": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "displayName": "Karoo Fresh Holdings Ltd", "blurb": "Budget deferred to the next financial year.", "unitPriceMonthly": 2900.0, "quantity": 3, "monthlyPrice": 10005.0, "seatsPerUnit": 1, "unlocks": [ "text" ], "maxQuantity": 3, "unitLabel": "Karoo Fresh Holdings Ltd" } ], "availableAddons": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "displayName": "Karoo Fresh Holdings Ltd", "blurb": "Budget deferred to the next financial year.", "unitPriceMonthly": 2900.0, "quantity": 3, "monthlyPrice": 10005.0, "seatsPerUnit": 1, "unlocks": [ "text" ], "maxQuantity": 3, "unitLabel": "Karoo Fresh Holdings Ltd" } ], "addonsMonthlyTotal": 10005.0, "addonUpgradeSuggestion": "The Business plan costs less than your current add-ons.", "apiKeysUsed": 1, "apiKeysIncluded": 1, "apiKeysHeadroom": 1, "apiKeysSummary": "Consulting services — August 2026" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/tenant-settings": { "get": { "tags": [ "Tenant, plan & entitlements" ], "summary": "The Settings screen's stored blob — company details, fiscal year, VAT profile, regional and notification preferences.", "operationId": "getApiTenantSettings", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiTenantSettingsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiTenantSettingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Tenant, plan & entitlements" ], "summary": "Save settings, section by section: each section you send replaces that section whole, and a section you leave out keeps its stored value. A body naming no known section is refused rather than answered 200. Every save writes one audit-log row listing each field it changed, from and to. Answers with the merged result.", "operationId": "putApiTenantSettings", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taxVat": { "type": "object", "properties": { "isVatRegistered": { "type": "boolean" }, "vatRegistrationDate": { "type": "string", "format": "date" }, "standardVatRate": { "type": "number" }, "drcEnabled": { "type": "boolean" }, "provisionalTaxPayer": { "type": "boolean" }, "sarsTaxRefNumber": { "type": "string" } } }, "branding": { "$ref": "#/components/schemas/PutApiTenantSettingsRequestBranding" }, "localisation": { "$ref": "#/components/schemas/PutApiTenantSettingsRequestLocalisation" }, "integrations": { "type": "object", "properties": { "whatsapp": { "type": "boolean" } } }, "notifications": { "type": "object", "properties": { "email-overdue-invoice": { "type": "boolean" }, "wa-overdue-followup": { "type": "boolean" } } }, "dataPrefs": { "$ref": "#/components/schemas/PutApiTenantSettingsRequestDataPrefs" } } }, "example": { "taxVat": { "isVatRegistered": true, "vatRegistrationDate": "2019-04-01", "standardVatRate": 15.0, "drcEnabled": false, "provisionalTaxPayer": true, "sarsTaxRefNumber": "9012345678" }, "branding": { "brandColorHex": "#0D47A1" }, "localisation": { "currency": "ZAR", "dateFormat": "day-month-year", "numberFormat": "space-point" }, "integrations": { "whatsapp": true }, "notifications": { "email-overdue-invoice": true, "wa-overdue-followup": false }, "dataPrefs": { "autoBackupEnabled": false, "autoBackupFrequency": "Daily", "retentionMonths": 84 } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiTenantSettingsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiTenantSettingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/tenant-settings/presentation": { "get": { "tags": [ "Tenant, plan & entitlements" ], "summary": "How the tenant chose to have Ledgr drawn — brand colour, date format and number format. Any member of the tenant may read it; the rest of the settings is Owner and Admin only.", "operationId": "getApiTenantSettingsPresentation", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "brandColorHex": { "type": "string" }, "dateFormat": { "type": "string" }, "numberFormat": { "type": "string" } } }, "example": { "brandColorHex": "#0D47A1", "dateFormat": "day-month-year", "numberFormat": "space-comma" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/approvals/waiting": { "get": { "tags": [ "Tenant, plan & entitlements" ], "summary": "What the signed-in person may decide: submitted expense claims, pending leave, purchase requisitions awaiting them and job cards awaiting sign-off. Each kind appears only with its approve permission and its module; lists are capped per kind, newest first, and the counts are the true totals.", "operationId": "getApiApprovalsWaiting", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "raisedBy": { "type": "string" }, "raisedAt": { "type": "string" } } } }, "counts": { "type": "object", "properties": { "claims": { "type": "integer" }, "leave": { "type": "integer" }, "requisitions": { "type": "integer" }, "jobSignOffs": { "type": "integer" } } }, "total": { "type": "integer" }, "perKindLimit": { "type": "integer" } } }, "example": { "items": [ { "kind": "claim", "id": "3f6b2a10-5c1e-4d7a-9b0e-2a8c4d6e8f01", "title": "R 517.50 · Fuel — Buyer User", "amount": 517.5, "currency": "ZAR", "raisedBy": "Buyer User", "raisedAt": "2026-10-10T07:15:00Z" } ], "counts": { "claims": 1, "leave": 0, "requisitions": 0, "jobSignOffs": 0 }, "total": 1, "perKindLimit": 50 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/data/export": { "post": { "tags": [ "Tenant, plan & entitlements" ], "summary": "A ZIP of CSVs — every table this tenant owns — and every file the tenant uploaded, byte for byte under files/, listed in files/manifest.csv. The export is what the retention notices lead with, because the Tax Administration Act asks a business to keep records for five years.", "operationId": "postApiDataExport", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "A file download.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/data/backups": { "get": { "tags": [ "Tenant, plan & entitlements" ], "summary": "The off-site backups Ledgr is holding for this tenant, plus what the schedule is doing. `nextDueOn` is null when automatic backups are switched off.", "operationId": "getApiDataBackups", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "backups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "takenOn": { "type": "string", "format": "date" }, "sizeBytes": { "type": "integer" }, "fileCount": { "type": "integer" }, "kind": { "type": "string" }, "status": { "type": "string" }, "error": { "type": "null" }, "frequency": { "type": "string" } } } }, "lastBackupAt": { "type": "string", "format": "date" }, "totalSizeBytes": { "type": "integer" }, "enabled": { "type": "boolean" }, "frequency": { "type": "string" }, "retentionMonths": { "type": "integer" }, "nextDueOn": { "type": "string", "format": "date" } } }, "example": { "backups": [ { "id": "72f394e2-8dc2-4722-9fc1-591469e089e6", "takenOn": "2026-09-03", "sizeBytes": 13367, "fileCount": 10, "kind": "auto", "status": "success", "error": null, "frequency": "daily" } ], "lastBackupAt": "2026-09-03", "totalSizeBytes": 13367, "enabled": true, "frequency": "daily", "retentionMonths": 84, "nextDueOn": "2026-09-04" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Tenant, plan & entitlements" ], "summary": "Back up now. Never deduped — pressing it twice takes two backups, unlike the scheduled run, which is idempotent per period.", "operationId": "postApiDataBackups", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "backup": { "type": "object", "properties": { "id": { "type": "string" }, "takenOn": { "type": "string", "format": "date" }, "sizeBytes": { "type": "integer" }, "fileCount": { "type": "integer" }, "kind": { "type": "string" }, "status": { "type": "string" }, "error": { "type": "null" }, "frequency": { "type": "null" } } }, "message": { "type": "null" }, "prunedCount": { "type": "integer" } } }, "example": { "ok": true, "backup": { "id": "72f394e2-8dc2-4722-9fc1-591469e089e6", "takenOn": "2026-09-03", "sizeBytes": 13367, "fileCount": 10, "kind": "manual", "status": "success", "error": null, "frequency": null }, "message": null, "prunedCount": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/data/backups/{id}/download": { "get": { "tags": [ "Tenant, plan & entitlements" ], "summary": "A short-lived signed URL for one backup. JSON rather than a 302: a redirect would carry the Ledgr bearer token to the storage host. Another tenant's id answers 404, never 403.", "operationId": "getApiDataBackupsByIdDownload", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "expiresInSeconds": { "type": "integer" } } }, "example": { "url": "https://storage.googleapis.com/ledgr-uploads/tenants/087df7f1/backups/23ed50ed.zip?X-Goog-Signature=abc", "expiresInSeconds": 300 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/data/backups/{id}/restore/preview": { "post": { "tags": [ "Tenant, plan & entitlements" ], "summary": "What restoring this backup WOULD do. Writes nothing. Its own endpoint rather than a flag on the write, so the safe call cannot become the dangerous one by a typo in a query string.", "operationId": "postApiDataBackupsByIdRestorePreview", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "applied": { "type": "boolean" }, "summary": { "type": "string" }, "restorable": { "type": "integer" }, "blocked": { "type": "integer" }, "unchanged": { "type": "integer" }, "byTable": { "$ref": "#/components/schemas/PostApiDataBackupsByIdRestoreResponseByTable" }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "table": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "date": { "type": "string", "format": "date" }, "verdict": { "type": "string" }, "reason": { "type": "string" } } } }, "decisionsTruncated": { "type": "boolean" }, "journalsReposted": { "type": "integer" }, "notRestorable": { "type": "null" } } }, "example": { "applied": false, "summary": "3 records can be put back, 1 cannot.", "restorable": 3, "blocked": 1, "unchanged": 41, "byTable": { "invoices": 1, "invoice_lines": 2 }, "decisions": [ { "table": "invoices", "id": "6a3f1c22-2f0f-4bd1-8f4f-1b2a5d3e9c77", "label": "INV-2026-014", "date": "2026-08-14", "verdict": "RESTORE", "reason": "Deleted since the backup — will be restored." } ], "decisionsTruncated": false, "journalsReposted": 0, "notRestorable": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/data/backups/{id}/restore": { "post": { "tags": [ "Tenant, plan & entitlements" ], "summary": "Put back records the books no longer hold. Adds only — never overwrites a live row and never deletes anything. A row inside a closed accounting period is refused with the period named; the ledger is re-posted by the posting engine rather than copied out of the backup.", "operationId": "postApiDataBackupsByIdRestore", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "applied": { "type": "boolean" }, "summary": { "type": "string" }, "restorable": { "type": "integer" }, "blocked": { "type": "integer" }, "unchanged": { "type": "integer" }, "byTable": { "$ref": "#/components/schemas/PostApiDataBackupsByIdRestoreResponseByTable" }, "decisions": { "type": "array", "items": { "type": "object" } }, "decisionsTruncated": { "type": "boolean" }, "journalsReposted": { "type": "integer" }, "notRestorable": { "type": "null" } } }, "example": { "applied": false, "summary": "3 records can be put back, 1 cannot.", "restorable": 3, "blocked": 1, "unchanged": 41, "byTable": { "invoices": 1, "invoice_lines": 2 }, "decisions": [], "decisionsTruncated": false, "journalsReposted": 2, "notRestorable": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/users": { "get": { "tags": [ "Users, roles & security" ], "summary": "Tenant users with their roles, 2FA state, session count and company access.", "operationId": "getApiUsers", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiUsersResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "email": "accounts@karoofresh.example", "firstName": "Karoo Fresh Holdings Ltd", "lastName": "Karoo Fresh Holdings Ltd", "role": "Accountant", "roleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true, "lastLoginAt": "2026-09-01T09:15:00Z", "twoFactorEnabled": false, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/users/invite": { "post": { "tags": [ "Users, roles & security" ], "summary": "Invite a colleague, choosing their role and which companies they may reach.", "operationId": "postApiUsersInvite", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "role": { "type": "string" }, "roleId": { "type": "string" }, "tempPassword": { "type": "string" }, "clientId": { "type": "string" }, "companyIds": { "type": "array", "items": { "type": "string" } } } }, "example": { "email": "accounts@karoofresh.example", "firstName": "Thandi", "lastName": "Mokoena", "role": "Accountant", "roleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tempPassword": "Welcome-2026!", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/GetApiUsersResponseItem" }, "tempPassword": { "type": "string" }, "emailed": { "type": "boolean" } } }, "example": { "user": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "email": "accounts@karoofresh.example", "firstName": "Karoo Fresh Holdings Ltd", "lastName": "Karoo Fresh Holdings Ltd", "role": "Accountant", "roleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true, "lastLoginAt": "2026-09-01T09:15:00Z", "twoFactorEnabled": false, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" }, "tempPassword": "", "emailed": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/users/{id}": { "put": { "tags": [ "Users, roles & security" ], "summary": "Change a user's name, role, active flag or company access.", "operationId": "putApiUsersById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string" }, "roleId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "isActive": { "type": "boolean" } } }, "example": { "role": "Accountant", "roleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "firstName": "Thandi", "lastName": "Mokoena", "isActive": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiUsersResponseItem" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "email": "accounts@karoofresh.example", "firstName": "Karoo Fresh Holdings Ltd", "lastName": "Karoo Fresh Holdings Ltd", "role": "Accountant", "roleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true, "lastLoginAt": "2026-09-01T09:15:00Z", "twoFactorEnabled": false, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Users, roles & security" ], "summary": "Deactivate a user and revoke their sessions.", "operationId": "deleteApiUsersById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/users/{id}/revoke-sessions": { "post": { "tags": [ "Users, roles & security" ], "summary": "Sign a user out everywhere without deactivating them.", "operationId": "postApiUsersByIdRevokeSessions", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "integer" } } }, "example": { "revoked": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/users/{id}/transfer-ownership": { "post": { "tags": [ "Users, roles & security" ], "summary": "Hand the tenant's single owner seat to another user. Gated harder than ordinary user management on purpose: `roles:edit` alone is not enough, because that permission is grantable to a custom role and giving away the god-mode seat is a different order of act from renaming one — only the current owner/admin may call it, and never on themselves. One transaction demotes the outgoing owner and promotes the target together, so the account is never briefly left with none or with two.", "operationId": "postApiUsersByIdTransferOwnership", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiUsersByIdTransferOwnershipRequest" }, "example": { "roleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "previousOwner": { "$ref": "#/components/schemas/GetApiUsersResponseItem" }, "newOwner": { "$ref": "#/components/schemas/GetApiUsersResponseItem" }, "message": { "type": "string" } } }, "example": { "previousOwner": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "email": "accounts@karoofresh.example", "firstName": "Karoo Fresh Holdings Ltd", "lastName": "Karoo Fresh Holdings Ltd", "role": "Accountant", "roleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true, "lastLoginAt": "2026-09-01T09:15:00Z", "twoFactorEnabled": false, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" }, "newOwner": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "email": "accounts@karoofresh.example", "firstName": "Karoo Fresh Holdings Ltd", "lastName": "Karoo Fresh Holdings Ltd", "role": "Accountant", "roleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true, "lastLoginAt": "2026-09-01T09:15:00Z", "twoFactorEnabled": false, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" }, "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/roles": { "get": { "tags": [ "Users, roles & security" ], "summary": "System and custom roles. The eight that ship are Owner, Admin, Accountant, Sales, Viewer, Payroll Manager, Tax Practitioner and External Auditor, plus Buyer, Production Planner and Fleet Controller where the plan carries them.", "operationId": "getApiRoles", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRolesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "isSystem": false, "permissions": [ { "resource": "invoices", "action": "created" } ], "userCount": 3, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Users, roles & security" ], "summary": "Create a custom role.", "operationId": "postApiRoles", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRolesRequestPermissionsItem" } } } }, "example": { "name": "Branch manager", "description": "Sells and banks, cannot see payroll", "permissions": [ { "resource": "invoices", "action": "view" } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRolesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRolesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/roles/{id}": { "put": { "tags": [ "Users, roles & security" ], "summary": "Rename or re-describe a role.", "operationId": "putApiRolesById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "example": { "name": "Branch manager", "description": "Consulting services — August 2026" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRolesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRolesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Users, roles & security" ], "summary": "Delete a custom role. A system role cannot be deleted.", "operationId": "deleteApiRolesById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/roles/{id}/permissions": { "get": { "tags": [ "Users, roles & security" ], "summary": "The full permission matrix for one role — every module against view, create, edit, delete, approve and export.", "operationId": "getApiRolesByIdPermissions", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRolesRequestPermissionsItem" } }, "example": [ { "resource": "invoices", "action": "created" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Users, roles & security" ], "summary": "Replace a role's permission matrix.", "operationId": "putApiRolesByIdPermissions", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRolesRequestPermissionsItem" } } } }, "example": { "permissions": [ { "resource": "invoices", "action": "view" } ] } } } }, "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/roles/my-permissions": { "get": { "tags": [ "Users, roles & security" ], "summary": "What the calling user may do, resolved. The client's nav guard reads this rather than inferring it from a role name.", "operationId": "getApiRolesMyPermissions", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "roleName": { "type": "string" }, "legacyRole": { "type": "string" }, "superuser": { "type": "boolean" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRolesRequestPermissionsItem" } } } }, "example": { "roleName": "Karoo Fresh Holdings Ltd", "legacyRole": "Accountant", "superuser": false, "permissions": [ { "resource": "invoices", "action": "created" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/audit-log": { "get": { "tags": [ "Users, roles & security" ], "summary": "Audit events with severity filtering; excludeSignIns=true leaves out sign-ins and sign-outs. Retained seven years for POPIA.", "operationId": "getApiAuditLog", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string" }, "example": "warning" }, { "name": "since", "in": "query", "required": false, "description": "Only rows changed at or after this instant, as an ISO 8601 timestamp.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "example": "sars.submit" }, { "name": "excludeSignIns", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "actorUserId": { "type": "string" }, "actorEmail": { "type": "string" }, "action": { "type": "string" }, "resourceType": { "type": "string" }, "resourceId": { "type": "string" }, "severity": { "type": "string" }, "payload": { "type": "string" }, "ipAddress": { "type": "string" }, "userAgent": { "type": "string" }, "createdAt": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "actorUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "actorEmail": "accounts@karoofresh.example", "action": "created", "resourceType": "standard", "resourceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "severity": "text", "payload": "text", "ipAddress": "12 Long Street, Cape Town, 8001", "userAgent": "text", "createdAt": "2026-09-01T09:15:00Z" } ], "total": 42, "page": 1, "limit": 50 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/security-policy": { "get": { "tags": [ "Users, roles & security" ], "summary": "Session timeout, password policy, lockout rules, whether admins must hold 2FA, and the retention period.", "operationId": "getApiSecurityPolicy", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiSecurityPolicyRequest" }, "examples": { "default": { "$ref": "#/components/examples/PutApiSecurityPolicyRequestExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Users, roles & security" ], "summary": "Replace the security policy — send every field, because one left out goes back to its default. The example body IS those defaults, so sending it as it stands changes nothing that would lock anyone out: change only the fields you mean to. Requiring 2FA for admins (require2faForAdmins: true) is enforced server-side, not advised to the client — every owner and admin without 2FA is limited to enrolling at their next sign-in, so enrol first.", "operationId": "putApiSecurityPolicy", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiSecurityPolicyRequest" }, "examples": { "default": { "$ref": "#/components/examples/PutApiSecurityPolicyRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiSecurityPolicyRequest" }, "examples": { "default": { "$ref": "#/components/examples/PutApiSecurityPolicyRequestExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/api-keys": { "get": { "tags": [ "API keys" ], "summary": "Keys for this tenant — name, scopes, bound contact, last use. The secret is never returned again.", "operationId": "getApiApiKeys", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "keyPrefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "contactId": { "type": "string" }, "lastUsedAt": { "type": "string" }, "expiresAt": { "type": "string" }, "revokedAt": { "type": "string" }, "createdAt": { "type": "string" }, "description": { "type": "string" }, "rateLimitPerMin": { "type": "integer" }, "requestCount": { "type": "integer" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "keyPrefix": "INV-", "scopes": [ "text" ], "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lastUsedAt": "2026-09-01T09:15:00Z", "expiresAt": "2026-09-01T09:15:00Z", "revokedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z", "description": "Consulting services — August 2026", "rateLimitPerMin": 1, "requestCount": 3 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "API keys" ], "summary": "Generate a key. The plaintext is shown ONCE in this response. Bind it to a contact if it will post billable events for one. Give actsAsRoleId to make a key the business owns: it acts with that role, not as you, and keeps working if you leave.", "operationId": "postApiApiKeys", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "contactId": { "type": "string" }, "expiresInDays": { "type": "integer" }, "description": { "type": "string" }, "rateLimitPerMin": { "type": "integer" }, "clientId": { "type": "string" }, "actsAsRoleId": { "type": "string" }, "workCentreIds": { "type": "array", "items": { "type": "object" } } } }, "example": { "name": "Warehouse sync", "scopes": [ "inventory:read", "inventory:write" ], "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "expiresInDays": 30, "description": "Consulting services — August 2026", "rateLimitPerMin": 1, "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "actsAsRoleId": "6b0e2d4a-9c1f-4e7a-8d35-1f2a3b4c5d6e", "workCentreIds": [] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "keyPrefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" } } }, "plaintextKey": { "type": "string" } } }, "example": { "key": { "id": "1da01faf-df19-565a-b682-5fc3d4eafa05", "tenantId": "a911913b-e9a4-58ad-8a64-74ca2f3990e3", "userId": "5ff68b17-8b62-5ca4-8994-991e33df27cd", "name": "Warehouse sync", "keyPrefix": "ledgr_live_9f2c", "scopes": [ "inventory:read", "inventory:write" ], "createdAt": "2026-09-01T09:00:00Z" }, "plaintextKey": "ledgr_live_… (shown once, never again)" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/api-keys/readiness/{integration}": { "get": { "tags": [ "API keys" ], "summary": "Whether this business holds a live, unexpired key whose scopes permit every call an API-key integration makes (integration: ruva). Read off the key table and the key gate's own scope rules.", "operationId": "getApiApiKeysReadinessByIntegration", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "integration", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "integration": { "type": "string" }, "ready": { "type": "boolean" }, "keyName": { "type": "string" }, "keyLastUsedAt": { "type": "string" }, "requiredScopes": { "type": "array", "items": { "type": "string" } } } }, "example": { "integration": "ruva", "ready": false, "keyName": "Ruva POS", "keyLastUsedAt": "2026-09-01T09:15:00Z", "requiredScopes": [ "multi-company:read", "reports:write" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/oauth/apps": { "get": { "tags": [ "API keys" ], "summary": "The apps this business has registered to connect to other Ledgr businesses through OAuth.", "operationId": "getApiOauthApps", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiOauthAppsResponseItem" } }, "example": [ { "id": "0c5a7e2b-3d4f-4a61-9b8c-2e1f0a9d7c35", "name": "Ledger Sync", "clientId": "lc_app_8Jx2Qm4Vt7Ry1Lp0", "redirectUris": [ "https://app.example.com/ledgr/callback" ], "createdAt": "2026-10-11T09:00:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "API keys" ], "summary": "Register an app. The client secret is shown ONCE in this response. Redirects must be https (http to localhost for testing) and are matched exactly.", "operationId": "postApiOauthApps", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "redirectUris": { "type": "array", "items": { "type": "string" } } } }, "example": { "name": "Ledger Sync", "redirectUris": [ "https://app.example.com/ledgr/callback" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/GetApiOauthAppsResponseItem" }, "clientSecret": { "type": "string" } } }, "example": { "app": { "id": "0c5a7e2b-3d4f-4a61-9b8c-2e1f0a9d7c35", "name": "Ledger Sync", "clientId": "lc_app_8Jx2Qm4Vt7Ry1Lp0", "redirectUris": [ "https://app.example.com/ledgr/callback" ], "createdAt": "2026-10-11T09:00:00Z" }, "clientSecret": "lcs_… (shown once, never again)" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/oauth/apps/{id}": { "delete": { "tags": [ "API keys" ], "summary": "Withdraw an app: no new connections, and no connection already made can refresh its token. Access tokens already issued lapse within the hour.", "operationId": "deleteApiOauthAppsById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/api-keys/{id}": { "delete": { "tags": [ "API keys" ], "summary": "Revoke a key. It stops working on the next request, not when its last token expires.", "operationId": "deleteApiApiKeysById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/api-keys/usage": { "get": { "tags": [ "API keys" ], "summary": "Per-key call counts and throttling. Metering is per replica, so a tenant's effective limit is N times the published one — see the KDoc on ApiKeyMetering.", "operationId": "getApiApiKeysUsage", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "How many days forward or back the window covers.", "schema": { "type": "integer" }, "example": "30" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "apiKeyId": { "type": "string" }, "name": { "type": "string" }, "keyPrefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "rateLimitPerMinute": { "type": "integer" }, "totalRequests": { "type": "integer" }, "lastUsedAt": { "type": "string" }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "requests": { "type": "integer" }, "clientErrors": { "type": "integer" }, "serverErrors": { "type": "integer" }, "throttled": { "type": "integer" } } } } } } }, "example": [ { "apiKeyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "keyPrefix": "INV-", "scopes": [ "text" ], "rateLimitPerMinute": 1, "totalRequests": 1, "lastUsedAt": "2026-09-01T09:15:00Z", "days": [ { "date": "2026-09-01", "requests": 1, "clientErrors": 0, "serverErrors": 0, "throttled": 1 } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/webhooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "The events a subscription may ask for, each with the API scope its data needs.", "operationId": "getApiWebhooksEvents", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "scope": { "type": "string" } } } }, "example": [ { "type": "standard", "label": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "scope": "text" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "This tenant's webhooks with the outcome of each one's most recent delivery. The signing secret is never returned again.", "operationId": "getApiWebhooks", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWebhooksResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "url": "https://app.ledgrsa.com/pay/3f1a7c92", "events": [ "text" ], "active": true, "secretHint": "text", "apiKeyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lastDeliveryStatus": "delivered", "lastDeliveryAt": "2026-09-01T09:15:00Z", "lastStatusCode": 1, "lastError": "text", "pendingCount": 3, "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Add a webhook. The signing secret is returned ONCE, in this response. Refused for a private or loopback address, an http:// address, or an event the caller's role or API key cannot read.", "operationId": "postApiWebhooks", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "clientId": { "type": "string" } } }, "example": { "name": "Online store", "url": "https://hooks.example/ledgr", "events": [ "logistics.stop.status_changed", "logistics.proof.recorded" ], "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/GetApiWebhooksResponseItem" }, "signingSecret": { "type": "string" } } }, "example": { "subscription": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "url": "https://app.ledgrsa.com/pay/3f1a7c92", "events": [ "text" ], "active": true, "secretHint": "text", "apiKeyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lastDeliveryStatus": "delivered", "lastDeliveryAt": "2026-09-01T09:15:00Z", "lastStatusCode": 1, "lastError": "text", "pendingCount": 3, "createdAt": "2026-09-01T09:15:00Z" }, "signingSecret": "" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/webhooks/{id}": { "put": { "tags": [ "Webhooks" ], "summary": "Change a webhook's name, address or events, or switch it off and on. Only the fields sent change. Events waiting while it was off are sent when it is switched back on.", "operationId": "putApiWebhooksById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" } } }, "example": { "name": "Online store", "url": "https://hooks.example/ledgr", "events": [ "logistics.stop.status_changed", "logistics.proof.recorded" ], "active": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWebhooksResponseItem" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "url": "https://app.ledgrsa.com/pay/3f1a7c92", "events": [ "text" ], "active": true, "secretHint": "text", "apiKeyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lastDeliveryStatus": "delivered", "lastDeliveryAt": "2026-09-01T09:15:00Z", "lastStatusCode": 1, "lastError": "text", "pendingCount": 3, "createdAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook. Anything still waiting to be sent to it is marked failed.", "operationId": "deleteApiWebhooksById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "The most recent deliveries to one webhook, newest first — status, attempts, the receiver's last HTTP status and why an attempt failed. Takes limit (1-200, default 50).", "operationId": "getApiWebhooksByIdDeliveries", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWebhooksByIdDeliveriesResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "eventId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "eventType": "standard", "status": "pending", "attempts": 1, "lastStatusCode": 1, "lastError": "text", "nextAttemptAt": "2026-09-01T09:15:00Z", "deliveredAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/webhooks/{id}/deliveries/{deliveryId}/redeliver": { "post": { "tags": [ "Webhooks" ], "summary": "Send a finished delivery again — the same event, under the same event id, so a receiver that dedupes by id takes it as the one it missed. Retried on the ordinary schedule if it fails again. 409 while the webhook is switched off or the delivery is still being tried.", "operationId": "postApiWebhooksByIdDeliveriesByDeliveryIdRedeliver", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWebhooksByIdDeliveriesResponseItem" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "eventId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "eventType": "standard", "status": "pending", "attempts": 1, "lastStatusCode": 1, "lastError": "text", "nextAttemptAt": "2026-09-01T09:15:00Z", "deliveredAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send one signed webhook.test event now and report what the receiver answered. Not retried.", "operationId": "postApiWebhooksByIdTest", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "statusCode": { "type": "integer" }, "error": { "type": "string" }, "eventId": { "type": "string" } } }, "example": { "delivered": true, "statusCode": 1, "error": "text", "eventId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/files/{id}": { "get": { "tags": [ "Files & attachments" ], "summary": "Returns a short-lived signed URL as JSON, deliberately NOT a 302: a redirect would carry your Ledgr token into Google's request logs, because HTTP clients re-send headers across a redirect. A miss answers 404, not 403, so an id cannot be probed for.", "operationId": "getApiFilesById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "variant", "in": "query", "required": false, "schema": { "type": "string" }, "example": "thumb" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "expiresInSeconds": { "type": "integer" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" } } }, "example": { "url": "https://storage.googleapis.com/…?X-Goog-Signature=…", "expiresInSeconds": 900, "contentType": "image/jpeg", "sizeBytes": 184320 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/tax-deadlines": { "get": { "tags": [ "Search, insights & deadlines" ], "summary": "The SARS calendar for this tenant, gated by its VAT category, employer registration and fiscal year end — so a non-employer is not chased for an EMP201. A period past its date stays listed, first and marked overdue (with daysLate and overdueCount), until its return is recorded as filed. For an employee ended as deceased it lists the certificate owed to the executor of the estate (type \"IRP5 to the executor\"), due 14 days after the death.", "operationId": "getApiTaxDeadlines", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "period": { "type": "string" }, "dueDate": { "type": "string", "format": "date" } } } }, "example": [ { "type": "standard", "period": "2026-09", "dueDate": "2026-09-01" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/alert-rules": { "get": { "tags": [ "Push notifications" ], "summary": "The signed-in person's own alert rules (market-platform T-P2.10): each a kind from a closed vocabulary with that person's numbers. Evaluated daily by the alert-rules job; a rule fires once per (rule, record, crossing) into its owner's inbox and push.", "operationId": "getApiAlertRules", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiAlertRulesResponse" } }, "example": [ { "id": "5d1e6a2b-8c4f-4b7e-9a31-0f2c7d9e1b44", "kind": "invoice-overdue", "amount": 50000.0, "days": 30, "description": "An invoice over R50000 overdue 30 days", "createdAt": "2026-10-11T08:00:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Push notifications" ], "summary": "Create an alert rule for the signed-in person. kind is one of invoice-overdue (amount, days), bank-balance-under (amount), bill-due-soon (days), stock-under-reorder, deal-untouched (days). Refused 403 when the caller's role cannot open the records the kind watches; at most 25 rules per person.", "operationId": "postApiAlertRules", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "amount": { "type": "number" }, "days": { "type": "integer" } } }, "example": { "kind": "invoice-overdue", "amount": 50000.0, "days": 30 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiAlertRulesResponse" }, "example": { "id": "5d1e6a2b-8c4f-4b7e-9a31-0f2c7d9e1b44", "kind": "invoice-overdue", "amount": 50000.0, "days": 30, "description": "An invoice over R50000 overdue 30 days", "createdAt": "2026-10-11T08:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/alert-rules/{id}": { "delete": { "tags": [ "Push notifications" ], "summary": "Delete one of the signed-in person's own alert rules. 404 for anybody else's.", "operationId": "deleteApiAlertRulesById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inbox": { "get": { "tags": [ "Push notifications" ], "summary": "The signed-in person's inbox (market-platform T-P2.9): every notification sent to them — each push topic, approval request, 'assigned to you' and emailed digest — newest first, with the unread count for the bell. Never anybody else's. Kept 90 days. ?limit= (default 30, max 100) and ?before= page back.", "operationId": "getApiInbox", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "30" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-10-11T08:30:00Z" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "topic": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "route": { "type": "string" }, "read": { "type": "boolean" }, "createdAt": { "type": "string" } } } }, "unread": { "type": "integer" } } }, "example": { "items": [ { "id": "8b0c2f1e-5a7d-4c39-9f6e-2d4a1b3c5e70", "topic": "push-payment-received", "title": "Payment received", "body": "R 4 600.00 received from Umlazi Bakery for INV-0042.", "route": "invoices", "read": false, "createdAt": "2026-10-11T07:42:10Z" } ], "unread": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inbox/unread": { "get": { "tags": [ "Push notifications" ], "summary": "How many of the signed-in person's inbox items are unread — the bell's badge.", "operationId": "getApiInboxUnread", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "unread": { "type": "integer" } } }, "example": { "unread": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inbox/read": { "post": { "tags": [ "Push notifications" ], "summary": "Mark the named items read — or, with no ids, everything — for the signed-in person only. Read here is read on every device.", "operationId": "postApiInboxRead", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInboxReadRequest" }, "example": { "ids": [ "8b0c2f1e-5a7d-4c39-9f6e-2d4a1b3c5e70" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "marked": { "type": "integer" }, "unread": { "type": "integer" } } }, "example": { "marked": 1, "unread": 2 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts. Filter by ?type=CUSTOMER|SUPPLIER|EMPLOYEE|TAX_PRACTITIONER.", "operationId": "getApiContacts", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Restrict to one type. Matched case-insensitively; an unrecognised value is refused.", "schema": { "type": "string" }, "example": "CUSTOMER" }, { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "search", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiContactsByIdResponse" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactType": "customer", "name": "Karoo Fresh Holdings Ltd", "tradingName": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "mobile": "+27 82 555 0143", "vatNumber": "4123456789", "registrationNo": "2021/123456/07", "creditLimit": 1.0, "creditUsed": 1.0, "addressLine1": "12 Long Street", "addressLine2": "Woodstock", "city": "Cape Town", "province": "Western Cape", "postalCode": "CT-001", "country": "South Africa", "postalAddressLine1": "12 Long Street", "postalAddressLine2": "Woodstock", "postalCity": "Cape Town", "postalProvince": "Western Cape", "postalPostalCode": "CT-001", "postalCountry": "South Africa", "currency": "ZAR", "paymentTerms": 1, "notes": "Budget deferred to the next financial year.", "isActive": true, "tags": [ "text" ], "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ], "total": 42, "page": 1, "limit": 50, "totalPages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Contacts" ], "summary": "Create a contact.", "operationId": "postApiContacts", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "contactType": { "type": "string" }, "name": { "type": "string" }, "tradingName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "mobile": { "type": "string" }, "vatNumber": { "type": "string" }, "registrationNo": { "type": "string" }, "creditLimit": { "type": "number" }, "groupCompanyId": { "type": "null" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" }, "postalAddressLine1": { "type": "string" }, "postalAddressLine2": { "type": "string" }, "postalCity": { "type": "string" }, "postalProvince": { "type": "string" }, "postalPostalCode": { "type": "string" }, "postalCountry": { "type": "string" }, "currency": { "type": "string" }, "paymentTerms": { "type": "integer" }, "notes": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "remindersPaused": { "type": "boolean" }, "connectedPerson": { "type": "boolean" }, "alsoCustomer": { "type": "boolean" }, "alsoSupplier": { "type": "boolean" }, "documentLanguage": { "type": "string" }, "customFields": { "type": "object", "properties": { "f1a2b3c4": { "type": "string" } } } } }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactType": "customer", "name": "Karoo Fresh Holdings Ltd", "tradingName": "Karoo Fresh Holdings Ltd", "email": "billing@acme.example", "phone": "+27210000000", "mobile": "+27 82 555 0143", "vatNumber": "4123456789", "registrationNo": "2021/123456/07", "creditLimit": 50000.0, "groupCompanyId": null, "addressLine1": "123 Long Street", "addressLine2": "Woodstock", "city": "Cape Town", "province": "Western Cape", "postalCode": "CT-001", "country": "ZA", "postalAddressLine1": "12 Long Street", "postalAddressLine2": "Woodstock", "postalCity": "Cape Town", "postalProvince": "Western Cape", "postalPostalCode": "CT-001", "postalCountry": "South Africa", "currency": "ZAR", "paymentTerms": 30, "notes": "Budget deferred to the next financial year.", "tags": [ "wholesale" ], "remindersPaused": false, "connectedPerson": false, "alsoCustomer": false, "alsoSupplier": false, "documentLanguage": "af", "customFields": { "f1a2b3c4": "Thandi Mokoena" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "contactType": { "type": "string" }, "name": { "type": "string" }, "creditLimit": { "type": "number" }, "creditUsed": { "type": "number" }, "createdAt": { "type": "string" } } }, "example": { "id": "18169b6d-4ef1-5921-a7b7-5ae5be060f91", "contactType": "customer", "name": "Acme Pty Ltd", "creditLimit": 50000.0, "creditUsed": 0.0, "createdAt": "2026-09-01T09:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/history-archive": { "get": { "tags": [ "Contacts" ], "summary": "A contact's settled documents and payments from before the switch, for reference. In no balance, ageing, VAT return or report.", "operationId": "getApiContactsByIdHistoryArchive", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "number": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "paidDate": { "type": "string", "format": "date" }, "total": { "type": "number" }, "vat": { "type": "number" }, "amountPaid": { "type": "number" }, "currency": { "type": "string" } } } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "reference": { "type": "string" }, "amount": { "type": "number" }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "documentNumber": { "type": "string" }, "amount": { "type": "number" } } } } } } } } }, "example": { "documents": [ { "kind": "invoice", "number": "INV-1042", "issueDate": "2025-11-03", "paidDate": "2025-12-01", "total": 1150.0, "vat": 150.0, "amountPaid": 1150.0, "currency": "ZAR" } ], "payments": [ { "date": "2025-12-01", "reference": "RCPT-9", "amount": 1150.0, "allocations": [ { "documentNumber": "INV-1042", "amount": 1150.0 } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}": { "get": { "tags": [ "Contacts" ], "summary": "One contact with its full detail grid and credit position.", "operationId": "getApiContactsById", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiContactsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Contacts" ], "summary": "Update a contact in place.", "operationId": "putApiContactsById", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "creditLimit": { "type": "number" } } }, "example": { "name": "Acme Pty Ltd", "email": "newbilling@acme.example", "creditLimit": 75000.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiContactsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "tags": [ "Contacts" ], "summary": "Apply an edit made against a copy of the contact, merged with anything changed since: fields nobody else changed are written, a field changed elsewhere to a different value answers 409 with both values and writes nothing, and a replayed edit id is answered as done.", "operationId": "patchApiContactsById", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchApiContactsByIdRequest" }, "examples": { "default": { "$ref": "#/components/examples/PatchApiContactsByIdRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiContactsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Contacts" ], "summary": "Soft-delete a contact.", "operationId": "deleteApiContactsById", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/sites": { "get": { "tags": [ "Contacts" ], "summary": "A customer's delivery sites — one per branch or depot they take delivery at — the default first.", "operationId": "getApiContactsByIdSites", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Contacts" ], "summary": "Add a delivery site. Refused without a name, or without a street address, town or postal code a driver can find. The first site, or one sent as the default, becomes the default.", "operationId": "postApiContactsByIdSites", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsByIdSitesRequest" }, "example": { "label": "Durban branch", "addressLine1": "12 Point Road", "addressLine2": null, "suburb": "Point", "city": "Durban", "postalCode": "4001", "province": "KwaZulu-Natal", "isDefault": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsByIdSitesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiContactsByIdSitesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/sites/{siteId}": { "put": { "tags": [ "Contacts" ], "summary": "Edit a delivery site. Documents that shipped there keep their own snapshot of the address.", "operationId": "putApiContactsByIdSitesBySiteId", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "siteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsByIdSitesRequest" }, "example": { "label": "Durban branch", "addressLine1": "40 Mahatma Gandhi Road", "addressLine2": null, "suburb": "Point", "city": "Durban", "postalCode": "4001", "province": "KwaZulu-Natal", "isDefault": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsByIdSitesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiContactsByIdSitesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Contacts" ], "summary": "Remove a delivery site. Documents and stops that used it keep their own copy of the address.", "operationId": "deleteApiContactsByIdSitesBySiteId", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "siteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/tags": { "patch": { "tags": [ "Contacts" ], "summary": "Set the badges — VIP, At Risk, NPO, B-BBEE level.", "operationId": "patchApiContactsByIdTags", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } } } }, "example": { "tags": [ "VIP", "BBBEE-2" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiContactsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/merge": { "post": { "tags": [ "Contacts" ], "summary": "Merge this contact into the survivor. Re-points every linked record rather than copying it, archives this contact, and records exactly what moved so the merge can be undone.", "operationId": "postApiContactsByIdMerge", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "survivorId": { "type": "string" } } }, "example": { "survivorId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "survivorId": { "type": "string" }, "mergeId": { "type": "string" }, "moved": { "type": "object", "properties": { "invoices": { "type": "integer" }, "contact_people": { "type": "integer" } } }, "contactId": { "type": "string" } } }, "example": { "ok": true, "survivorId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "mergeId": "8d2e4b17-0c3a-4f59-b6e2-91a7d5c3e804", "moved": { "invoices": 3, "contact_people": 1 }, "contactId": "5b9c2e71-8a44-4d13-a0f6-3e7d1c9b2a55" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/merge": { "post": { "tags": [ "Contacts" ], "summary": "Merge several duplicates into one survivor in one request. Each is recorded as its own merge, so each can be undone on its own; one contact that cannot be merged refuses the lot.", "operationId": "postApiContactsMerge", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "survivorId": { "type": "string" }, "contactIds": { "type": "array", "items": { "type": "string" } } } }, "example": { "survivorId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "survivorId": { "type": "string" }, "merges": { "type": "array", "items": { "type": "object", "properties": { "ok": { "type": "boolean" }, "survivorId": { "type": "string" }, "mergeId": { "type": "string" }, "moved": { "$ref": "#/components/schemas/PostApiContactsMergeResponseMergesItemMoved" }, "contactId": { "type": "string" } } } } } }, "example": { "survivorId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "merges": [ { "ok": true, "survivorId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "mergeId": "8d2e4b17-0c3a-4f59-b6e2-91a7d5c3e804", "moved": { "invoices": 2 }, "contactId": "5b9c2e71-8a44-4d13-a0f6-3e7d1c9b2a55" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/merges/{mergeId}/undo": { "post": { "tags": [ "Contacts" ], "summary": "Undo a merge: the records it moved go back to the contact it archived, which is restored. Anything the survivor gained after the merge stays with the survivor.", "operationId": "postApiContactsMergesByMergeIdUndo", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "mergeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "mergeId": { "type": "string" }, "contactId": { "type": "string" }, "survivorId": { "type": "string" }, "movedBack": { "$ref": "#/components/schemas/PostApiContactsMergeResponseMergesItemMoved" }, "message": { "type": "string" } } }, "example": { "mergeId": "8d2e4b17-0c3a-4f59-b6e2-91a7d5c3e804", "contactId": "5b9c2e71-8a44-4d13-a0f6-3e7d1c9b2a55", "survivorId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "movedBack": { "invoices": 2 }, "message": "Dup Co is restored with 2 records moved back." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/restore": { "post": { "tags": [ "Contacts" ], "summary": "Bring an archived contact back. A contact archived by a merge is refused, naming the merge to undo instead.", "operationId": "postApiContactsByIdRestore", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactType": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "example": { "id": "5b9c2e71-8a44-4d13-a0f6-3e7d1c9b2a55", "tenantId": "c4a17e90-2d35-4b8f-9e61-7a0d3f5b2c18", "contactType": "customer", "name": "Acme Trading", "createdAt": "2026-09-01T08:00:00Z", "updatedAt": "2026-09-16T10:12:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/bills": { "get": { "tags": [ "Contacts" ], "summary": "The supplier half of an account: this contact's bills, newest first, and what is still owed on them. Needs expenses:view as well as contacts:view; the balance alone is /api/contacts/{id}/balance.", "operationId": "getApiContactsByIdBills", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "bills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "billNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "vatAmount": { "type": "number" }, "total": { "type": "number" }, "status": { "type": "string" } } } }, "owed": { "type": "number" }, "openCount": { "type": "integer" }, "total": { "type": "integer" }, "limit": { "type": "integer" } } }, "example": { "bills": [ { "id": "8d2e4b17-0c3a-4f59-b6e2-91a7d5c3e804", "billNumber": "TKM-7741290", "issueDate": "2026-08-06", "dueDate": "2026-09-05", "amount": 2868.57, "vatAmount": 430.29, "total": 3298.86, "status": "due" } ], "owed": 3298.86, "openCount": 1, "total": 1, "limit": 100 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/balance": { "get": { "tags": [ "Contacts" ], "summary": "What a contact owes and is owed, without the documents behind it: the receivable ageing, what is owed on open bills, and the statement's open items as the statement PDF prints them. On contacts:view alone; the invoice and bill lists need invoices:view and expenses:view.", "operationId": "getApiContactsByIdBalance", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-11-10" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ageing": { "$ref": "#/components/schemas/GetApiContactsByIdBalanceResponseAgeing" }, "owed": { "type": "number" }, "openBillCount": { "type": "integer" }, "statementItems": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiContactsByIdInvoicesResponseInvoicesItem" } } } }, "example": { "ageing": { "current": 11500.0, "days30": 0.0, "days60": 0.0, "days90": 0.0, "overdue": 0.0, "days1to30": 0.0, "notYetDue": 11500.0 }, "owed": 3298.86, "openBillCount": 1, "statementItems": [ { "id": "", "number": "INV-0042", "documentType": "invoice", "issueDate": "2026-11-01", "dueDate": "2026-12-01", "total": 11500.0, "amountDue": 11500.0, "status": "open" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/price-list": { "get": { "tags": [ "Contacts" ], "summary": "The customer's default price list, with every price on it — what their invoices, quotes, job cards and portal orders are priced from. No list is a null priceList.", "operationId": "getApiContactsByIdPriceList", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsByIdPriceListResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiContactsByIdPriceListResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Contacts" ], "summary": "Choose the customer's default price list; a null priceListId clears it.", "operationId": "putApiContactsByIdPriceList", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priceListId": { "type": "string" } } }, "example": { "priceListId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsByIdPriceListResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiContactsByIdPriceListResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/people": { "get": { "tags": [ "Contacts" ], "summary": "The people at a contact — accounts, buyers, directors — each with their own address.", "operationId": "getApiContactsByIdPeople", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiContactsByIdPeopleResponse" } }, "example": [ { "id": "8d2e4b17-0c3a-4f59-b6e2-91a7d5c3e804", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Thandi Mokoena", "role": "accounts", "email": "accounts@acme.example", "phone": "+27 11 555 0101", "includeInStatements": false, "createdAt": "2026-09-16T10:00:00Z", "updatedAt": "2026-09-16T10:00:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Contacts" ], "summary": "Add a person to a contact. A person marked to receive statements must have an email address.", "operationId": "postApiContactsByIdPeople", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsByIdPeopleRequest" }, "example": { "name": "Thandi Mokoena", "role": "accounts", "email": "accounts@acme.example", "phone": "+27 11 555 0101", "includeInStatements": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsByIdPeopleResponse" }, "example": { "id": "8d2e4b17-0c3a-4f59-b6e2-91a7d5c3e804", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Thandi Mokoena", "role": "accounts", "email": "accounts@acme.example", "phone": "+27 11 555 0101", "includeInStatements": false, "createdAt": "2026-09-16T10:00:00Z", "updatedAt": "2026-09-16T10:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/people/{personId}": { "put": { "tags": [ "Contacts" ], "summary": "Replace a person's details.", "operationId": "putApiContactsByIdPeopleByPersonId", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "personId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsByIdPeopleRequest" }, "example": { "name": "Thandi Mokoena", "role": "accounts", "email": "payables@acme.example", "phone": "+27 11 555 0101", "includeInStatements": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsByIdPeopleResponse" }, "example": { "id": "8d2e4b17-0c3a-4f59-b6e2-91a7d5c3e804", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Thandi Mokoena", "role": "accounts", "email": "payables@acme.example", "phone": "+27 11 555 0101", "includeInStatements": false, "createdAt": "2026-09-16T10:00:00Z", "updatedAt": "2026-09-16T11:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Contacts" ], "summary": "Remove a person from a contact.", "operationId": "deleteApiContactsByIdPeopleByPersonId", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "personId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/invoices": { "get": { "tags": [ "Contacts" ], "summary": "Every document raised against this contact.", "operationId": "getApiContactsByIdInvoices", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiContactsByIdInvoicesResponseInvoicesItem" } }, "ageing": { "$ref": "#/components/schemas/GetApiContactsByIdBalanceResponseAgeing" }, "total": { "type": "integer" }, "limit": { "type": "integer" } } }, "example": { "invoices": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "INV-0001", "documentType": "invoice", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "total": 10005.0, "amountDue": 10005.0, "status": "sent" } ], "ageing": { "current": 1.0, "days30": 1.0, "days60": 1.0, "days90": 1.0, "overdue": 1.0, "days1to30": 1.0, "notYetDue": 1.0 }, "total": 42, "limit": 50 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/communications": { "get": { "tags": [ "Contacts" ], "summary": "The communication timeline — emails, WhatsApps, statements sent, plus CRM activities merged in server-side.", "operationId": "getApiContactsByIdCommunications", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "description": "How many rows to skip. Use with `limit` to page. A paged response reports `total`, which is the number of rows matching the filter rather than the number returned.", "schema": { "type": "integer" }, "example": "0" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiContactsByIdCommunicationsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "channel": "email", "direction": "text", "subject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached.", "relatedDoc": "text", "status": "sent", "errorMessage": "Saved.", "occurredAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Contacts" ], "summary": "Log a communication by hand.", "operationId": "postApiContactsByIdCommunications", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string" }, "direction": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "relatedDoc": { "type": "string" } } }, "example": { "channel": "phone", "direction": "outbound", "subject": "Chased the March invoice", "body": "Promised payment Friday.", "relatedDoc": "INV-0001" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsByIdCommunicationsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "channel": "email", "direction": "text", "subject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached.", "relatedDoc": "text", "status": "sent", "errorMessage": "Saved.", "occurredAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/statement.pdf": { "get": { "tags": [ "Contacts" ], "summary": "The customer statement as a PDF: open items as at ?asOf=, or ?kind=activity&from=&to= for everything that happened on the account in a period, between an opening and a closing balance.", "operationId": "getApiContactsByIdStatement.pdf", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "example": "activity" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/send-statement": { "post": { "tags": [ "Contacts" ], "summary": "Send the statement by email or WhatsApp. By email it goes to the contact's address and to every person marked to receive statements, one email each. An open-items statement as at asOf (today when absent) is the account at that date — the customer's line on aged debtors that day; an asOf that is not a real date is refused with a 400.", "operationId": "postApiContactsByIdSendStatement", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string" }, "toEmail": { "type": "string" }, "asOf": { "type": "string", "format": "date" }, "kind": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "example": { "channel": "email", "toEmail": "accounts@karoofresh.example", "asOf": "2026-09-30", "kind": "activity", "from": "2026-08-01", "to": "2026-08-31" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "contactId": { "type": "string" }, "channel": { "type": "string" }, "outstanding": { "type": "number" }, "invoiceCount": { "type": "integer" }, "failReason": { "type": "string" } } }, "example": { "ok": true, "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "channel": "email", "outstanding": 1.0, "invoiceCount": 3, "failReason": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/account-stop": { "put": { "tags": [ "Contacts" ], "summary": "Put an account on stop, with a reason, or take it off. No invoice is issued to a stopped account unless someone holding invoices:approve overrides it.", "operationId": "putApiContactsByIdAccountStop", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stopped": { "type": "boolean" }, "reason": { "type": "string" } } }, "example": { "stopped": true, "reason": "Cheque returned twice" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "onStop": { "type": "boolean" }, "reason": { "type": "string" } } }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "onStop": true, "reason": "Cheque returned twice" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/promises": { "post": { "tags": [ "Contacts" ], "summary": "Note what a debtor said they would pay and by when. A note for credit control: it moves no money.", "operationId": "postApiContactsByIdPromises", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "promisedDate": { "type": "string", "format": "date" }, "note": { "type": "string" }, "amount": { "type": "number" } } }, "example": { "promisedDate": "2026-11-07", "note": "Sipho will pay half on Friday", "amount": 5000.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "promisedDate": { "type": "string", "format": "date" }, "note": { "type": "string" }, "amount": { "type": "number" }, "status": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "promisedDate": "2026-11-07", "note": "Sipho will pay half on Friday", "amount": 5000.0, "status": "open" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/promises/{promiseId}/close": { "post": { "tags": [ "Contacts" ], "summary": "Mark a promise dealt with, kept or not.", "operationId": "postApiContactsPromisesByPromiseIdClose", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "promiseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsPromisesResponseItem" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "promisedDate": "2026-11-07", "note": "Sipho will pay half on Friday", "status": "closed" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/promises": { "get": { "tags": [ "Contacts" ], "summary": "Every open promise of the active company, earliest first.", "operationId": "getApiContactsPromises", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiContactsPromisesResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "promisedDate": "2026-11-07", "note": "Sipho will pay half on Friday", "status": "open" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/aged-debtors": { "get": { "tags": [ "Contacts" ], "summary": "Aged debtors per customer in the five bands Reports draws — notYetDue, days1to30, days30 (31–60), days60 (61–90) and days90 (90+), which add up to total. current is the 0–30 roll-up (notYetDue + days1to30); overdue is everything past due.", "operationId": "getApiContactsAgedDebtors", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "type": "string" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiContactsAgedDebtorsResponseTotals" } }, "totals": { "$ref": "#/components/schemas/GetApiContactsAgedDebtorsResponseTotals" }, "ledgerControlBalance": { "type": "number" }, "controlDifference": { "type": "number" } } }, "example": { "asOf": "text", "rows": [ { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "current": 1.0, "days30": 1.0, "days60": 1.0, "days90": 1.0, "total": 10005.0, "overdue": 1.0, "days1to30": 1.0, "notYetDue": 1.0 } ], "totals": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "current": 1.0, "days30": 1.0, "days60": 1.0, "days90": 1.0, "total": 10005.0, "overdue": 1.0, "days1to30": 1.0, "notYetDue": 1.0 }, "ledgerControlBalance": 10005.0, "controlDifference": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/summary": { "get": { "tags": [ "Contacts" ], "summary": "Counts for the whole address book — by type, VIP-tagged, and customers at risk (tagged, or owing money past its due date).", "operationId": "getApiContactsSummary", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "customers": { "type": "integer" }, "suppliers": { "type": "integer" }, "employees": { "type": "integer" }, "practitioners": { "type": "integer" }, "starred": { "type": "integer" }, "atRisk": { "type": "integer" } } }, "example": { "total": 58, "customers": 54, "suppliers": 4, "employees": 0, "practitioners": 0, "starred": 3, "atRisk": 9 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/portal-link": { "get": { "tags": [ "Contacts" ], "summary": "The customer's self-service portal link. The token travels in the URL path, which is why this is minted rather than guessable.", "operationId": "getApiContactsByIdPortalLink", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "url": { "type": "string" } } }, "example": { "token": "", "url": "https://app.ledgrsa.com/pay/3f1a7c92" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/portal-link/revoke": { "post": { "tags": [ "Contacts" ], "summary": "Reissue one document's customer link: every link already sent for it stops opening, and the response carries the replacement. The contact's revoke is the wider act.", "operationId": "postApiInvoicesByIdPortalLinkRevoke", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "portalTokenVersion": { "type": "integer" }, "token": { "type": "string" }, "url": { "type": "string" }, "validDays": { "type": "integer" } } }, "example": { "invoiceId": "7c2e4b10-9d3a-4f61-b8e2-5a1c0f9d3e47", "portalTokenVersion": 2, "token": "", "url": "https://app.ledgrsa.com/portal/invoice/", "validDays": 30 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/portal-link/revoke": { "post": { "tags": [ "Contacts" ], "summary": "Retire every portal link this contact holds — the statement, the ordering portal and the link inside each of their documents — by moving the token generations on.", "operationId": "postApiContactsByIdPortalLinkRevoke", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" }, "portalTokenVersion": { "type": "integer" } } }, "example": { "revoked": false, "portalTokenVersion": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/export": { "get": { "tags": [ "Contacts" ], "summary": "The whole contact book as a CSV, in the same columns the contact import reads, plus one column per field your business defined for contacts, headed with its name — so the file comes back in through the import unchanged. Every cell is quoted and a cell that would start a spreadsheet formula is neutralised. Refused rather than cut short past the import's row limit. `contacts:export`.", "operationId": "getApiContactsExport", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/consent": { "get": { "tags": [ "Contacts" ], "summary": "This contact's direct-marketing consent (POPIA section 69): where each channel — email, WhatsApp, SMS, phone — stands now, and every event recorded, newest first. No record on a channel means no consent. Invoices, statements, reminders, quotes and payslips are not marketing and are not gated by it.", "operationId": "getApiContactsByIdConsent", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsByIdConsentResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiContactsByIdConsentResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Contacts" ], "summary": "Record one consent event: given or withdrawn, on one channel, with how it was obtained. Never an edit — a correction is a new event, so the history cannot be rewritten. Also written to the audit log.", "operationId": "postApiContactsByIdConsent", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string" }, "status": { "type": "string" }, "method": { "type": "string" }, "note": { "type": "string" } } }, "example": { "channel": "email", "status": "given", "method": "online_form", "note": "Ticked the newsletter box on the quote acceptance page." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsByIdConsentResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiContactsByIdConsentResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/personal-data": { "get": { "tags": [ "Contacts" ], "summary": "Everything held about one person, for a POPIA access request: their contact record, every record that names them (invoices, quotes, bills, consent events, deals…) and those records' lines, as one JSON object keyed by table. Nobody else's rows. Pay records need payroll access. Needs contacts view.", "operationId": "getApiContactsByIdPersonalData", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/anonymise": { "post": { "tags": [ "Contacts" ], "summary": "Erase one person's details at their request: name, email, phones, addresses, bank details and notes are cleared, marketing consent is withdrawn on every channel, and the business's own records are kept under an anonymised name. Refused (409), naming the record and the date, while an invoice or bill naming them is inside the years the business must keep it: seven for a company, close corporation or non-profit company (Companies Act s24), five for a sole proprietor, partnership or trust (Tax Administration Act s29), the five counted from the day the return covering the record was submitted (s29(3)(a)), and with no end while no return covering it is recorded as filed. Written to the audit log. Needs contacts delete.", "operationId": "postApiContactsByIdAnonymise", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "consentWithdrawn": { "type": "array", "items": { "type": "string" } } } }, "example": { "id": "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e", "name": "Anonymised contact 3c2b1a09", "consentWithdrawn": [ "email", "whatsapp", "sms", "phone" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/information-officer": { "get": { "tags": [ "Contacts" ], "summary": "The information officer of the company in X-Company-Id (POPIA s55): name, email, phone and the Information Regulator registration, and the sentence a person asking about their information is given. recorded is false until one is named, and the sentence then says that under POPIA the head of the business is its information officer until another is named. Needs contacts view.", "operationId": "getApiContactsInformationOfficer", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsInformationOfficerResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiContactsInformationOfficerResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Contacts" ], "summary": "Name the information officer of the company in X-Company-Id (POPIA s55). A name and an email address are required (400 otherwise); phone and the Information Regulator registration are optional. The officer is then named in each person's own export and in a refusal to erase their details. Written to the audit log. Needs multicompany edit, as the company profile does.", "operationId": "putApiContactsInformationOfficer", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsInformationOfficerResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiContactsInformationOfficerResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/ownership-register": { "get": { "tags": [ "Contacts" ], "summary": "The securities and beneficial ownership register of the company in X-Company-Id (Companies Act s50 and s56, Companies Regulations reg 32(3)): every securities holder and beneficial owner, current and ceased, with ID numbers opened for the reader, and its dated changes, newest first, each with the date its CIPC declaration is due (10 business days on, reg 32(3A)) unless entered as already declared. statement says what the register owes CIPC now. Needs multicompany view.", "operationId": "getApiContactsOwnershipRegister", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiContactsOwnershipRegisterResponse" } }, "changes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "entryId": { "type": "string" }, "change": { "type": "string" }, "changedOn": { "type": "string", "format": "date" }, "alreadyDeclared": { "type": "boolean" }, "summary": { "type": "string" }, "declarationDue": { "type": "string", "format": "date" } } } }, "statement": { "type": "string" } } }, "example": { "companyId": "8b5d2f1e-3c4a-4e9b-a7d6-1f2e3c4b5a69", "entries": [ { "id": "5c1e9a7b-2d3f-4e8a-9b6c-0d1e2f3a4b5c", "kind": "BENEFICIAL_OWNER", "juristic": false, "surname": "Dlamini", "names": "Naledi", "idNumber": "8001015009087", "saCitizen": true, "nationality": "South Africa", "countryOfResidence": "South Africa", "dateOfBirth": "1980-01-01", "email": "naledi@karoofresh.example", "mobile": "0825550101", "interestTypes": [ "SHAREHOLDING" ], "percentage": 60.0, "physicalAddress": "12 Long Street", "city": "Cape Town", "province": "Western Cape", "postalCode": "8001", "postalAddress": "PO Box 1, Cape Town, 8000", "securitiesClass": "Ordinary shares", "securitiesCount": 60.0, "certificateNumber": "003", "amountPaid": 60.0, "acquiredOn": "2026-11-02", "ceasedOn": null, "active": true } ], "changes": [ { "id": "7a2b3c4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d", "entryId": "5c1e9a7b-2d3f-4e8a-9b6c-0d1e2f3a4b5c", "change": "ADDED", "changedOn": "2026-11-02", "alreadyDeclared": false, "summary": "Naledi Dlamini recorded as a beneficial owner (60.00%)", "declarationDue": "2026-11-16" } ], "statement": "1 beneficial owner(s) and 0 securities holder(s) are on the register. Download the declaration to file it on CIPC's portal. A recorded change is to be declared to CIPC by 2026-11-16." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Contacts" ], "summary": "Record a securities holder or a beneficial owner on the register of the company in X-Company-Id. A beneficial owner is a natural person (juristic true is refused) with at least one of CIPC's interest types; a shareholding or voting right needs its percentage; a securities holder needs the class and number of securities. acquiredOn is the date of interest. Unless alreadyDeclared (an interest CIPC already holds, typed in once), the change is due to CIPC within 10 business days and appears on the tax calendar as CIPC Beneficial Ownership change. The ID number is sealed at rest. Written to the audit log. Needs multicompany edit.", "operationId": "postApiContactsOwnershipRegister", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsOwnershipRegisterResponse" }, "example": { "id": "5c1e9a7b-2d3f-4e8a-9b6c-0d1e2f3a4b5c", "kind": "BENEFICIAL_OWNER", "juristic": false, "surname": "Dlamini", "names": "Naledi", "idNumber": "8001015009087", "saCitizen": true, "nationality": "South Africa", "countryOfResidence": "South Africa", "dateOfBirth": "1980-01-01", "email": "naledi@karoofresh.example", "mobile": "0825550101", "interestTypes": [ "SHAREHOLDING" ], "percentage": 60.0, "physicalAddress": "12 Long Street", "city": "Cape Town", "province": "Western Cape", "postalCode": "8001", "postalAddress": "PO Box 1, Cape Town, 8000", "securitiesClass": "Ordinary shares", "securitiesCount": 60.0, "certificateNumber": "003", "amountPaid": 60.0, "acquiredOn": "2026-11-02", "ceasedOn": null, "active": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/ownership-register/declaration": { "get": { "tags": [ "Contacts" ], "summary": "The CIPC beneficial ownership declaration and securities register as at asAt (default today), as a CSV to download and type into CIPC's portal (Ledgr does not file it): the company, then the beneficial owners held on that date in the order CIPC's filing asks for the fields (citizen, date of birth, ID or passport, name, surname, email, mobile, country of residence, country of origin, date of interest, interest type, percentage, address), then the securities holders in the order of CIPC's securities register template. More than ten owners adds the line that CIPC takes the rest on a disclosure form. Needs multicompany view.", "operationId": "getApiContactsOwnershipRegisterDeclaration", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asAt", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-11-08" } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/ownership-register/{entryId}": { "put": { "tags": [ "Contacts" ], "summary": "Change an interest on the register: the same body as recording one, with changedOn, the date the change took effect (required, not in the future). A ceased interest is refused. The change is dated and, unless alreadyDeclared, due to CIPC within 10 business days. Written to the audit log. Needs multicompany edit.", "operationId": "putApiContactsOwnershipRegisterByEntryId", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsOwnershipRegisterResponse" }, "example": { "id": "5c1e9a7b-2d3f-4e8a-9b6c-0d1e2f3a4b5c", "kind": "BENEFICIAL_OWNER", "juristic": false, "surname": "Dlamini", "names": "Naledi", "idNumber": "8001015009087", "saCitizen": true, "nationality": "South Africa", "countryOfResidence": "South Africa", "dateOfBirth": "1980-01-01", "email": "naledi@karoofresh.example", "mobile": "0825550101", "interestTypes": [ "SHAREHOLDING" ], "percentage": 55.0, "physicalAddress": "12 Long Street", "city": "Cape Town", "province": "Western Cape", "postalCode": "8001", "postalAddress": "PO Box 1, Cape Town, 8000", "securitiesClass": "Ordinary shares", "securitiesCount": 60.0, "certificateNumber": "003", "amountPaid": 60.0, "acquiredOn": "2026-11-02", "ceasedOn": null, "active": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/ownership-register/{entryId}/cease": { "post": { "tags": [ "Contacts" ], "summary": "Record that an interest ended on ceasedOn (not in the future, not before it was acquired). The row stays on the register as history; the change is due to CIPC within 10 business days unless alreadyDeclared. Written to the audit log. Needs multicompany edit.", "operationId": "postApiContactsOwnershipRegisterByEntryIdCease", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "juristic": { "type": "boolean" }, "surname": { "type": "string" }, "names": { "type": "string" }, "idNumber": { "type": "string" }, "saCitizen": { "type": "boolean" }, "nationality": { "type": "string" }, "countryOfResidence": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "interestTypes": { "type": "array", "items": { "type": "string" } }, "percentage": { "type": "number" }, "physicalAddress": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "postalCode": { "type": "string" }, "postalAddress": { "type": "string" }, "securitiesClass": { "type": "string" }, "securitiesCount": { "type": "number" }, "certificateNumber": { "type": "string" }, "amountPaid": { "type": "number" }, "acquiredOn": { "type": "string", "format": "date" }, "ceasedOn": { "type": "string", "format": "date" }, "active": { "type": "boolean" } } }, "example": { "id": "5c1e9a7b-2d3f-4e8a-9b6c-0d1e2f3a4b5c", "kind": "BENEFICIAL_OWNER", "juristic": false, "surname": "Dlamini", "names": "Naledi", "idNumber": "8001015009087", "saCitizen": true, "nationality": "South Africa", "countryOfResidence": "South Africa", "dateOfBirth": "1980-01-01", "email": "naledi@karoofresh.example", "mobile": "0825550101", "interestTypes": [ "SHAREHOLDING" ], "percentage": 60.0, "physicalAddress": "12 Long Street", "city": "Cape Town", "province": "Western Cape", "postalCode": "8001", "postalAddress": "PO Box 1, Cape Town, 8000", "securitiesClass": "Ordinary shares", "securitiesCount": 60.0, "certificateNumber": "003", "amountPaid": 60.0, "acquiredOn": "2026-11-02", "ceasedOn": "2026-11-06", "active": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/marketing-audience": { "get": { "tags": [ "Contacts" ], "summary": "CSV of the contacts who may be sent marketing on one channel — only those whose newest event on it is consent given. The one way a marketing list leaves Ledgr, so it can only leave through the rule. Needs contacts:export.", "operationId": "getApiContactsMarketingAudience", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "channel", "in": "query", "required": false, "schema": { "type": "string" }, "example": "email" } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/customer-portal": { "get": { "tags": [ "Contacts" ], "summary": "Whether this customer is opted in to the ordering portal, their link, when they last opened it, and how many products it offers them (zero means the link opens an empty price list). Each call issues a fresh link; pass ?mint=false to read the state without issuing one. The token travels in the link's path and is redacted from every log line and error body.", "operationId": "getApiContactsByIdCustomerPortal", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "mint", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "false" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsByIdCustomerPortalResponse" }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "customerName": "Acme Trading", "enabled": false, "token": "", "url": "https://app.ledgrsa.com/customer-portal/", "expiresAt": "2027-09-11T08:14:00Z", "lastSeenAt": "2026-09-10T14:02:11Z", "offeredProductCount": 240 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Contacts" ], "summary": "Open or close the ordering portal for one customer. Closing also bumps their token generation, so every link already sent stops working. Opening needs the Inventory module — the portal lists the products offered from it — and is refused with 403 MODULE_NOT_LICENSED on a plan without it; closing is never refused.", "operationId": "postApiContactsByIdCustomerPortal", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsByIdCustomerPortalRequest" }, "example": { "enabled": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsByIdCustomerPortalResponse" }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "customerName": "Acme Trading", "enabled": true, "token": "", "url": "https://app.ledgrsa.com/customer-portal/", "expiresAt": "2027-09-11T08:14:00Z", "lastSeenAt": "2026-09-10T14:02:11Z", "offeredProductCount": 240 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/customer-portal/confirms-orders": { "post": { "tags": [ "Contacts" ], "summary": "Whether this customer's ordering-portal baskets confirm themselves. On, a basket becomes a sales order at sent that holds its stock and posts nothing; a basket that would over-reserve still comes in as a draft quote naming the short item. Refused with 409 while the portal is closed, and turned off when the portal is closed. A body that cannot be read changes nothing (400). Mints no link. Requires invoices:edit.", "operationId": "postApiContactsByIdCustomerPortalConfirmsOrders", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmsOrders": { "type": "boolean" } } }, "example": { "confirmsOrders": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "customerName": { "type": "string" }, "enabled": { "type": "boolean" }, "token": { "type": "null" }, "url": { "type": "null" }, "expiresAt": { "type": "null" }, "lastSeenAt": { "type": "string" }, "offeredProductCount": { "type": "integer" }, "confirmsOrders": { "type": "boolean" } } }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "customerName": "Acme Trading", "enabled": true, "token": null, "url": null, "expiresAt": null, "lastSeenAt": "2026-09-10T14:02:11Z", "offeredProductCount": 240, "confirmsOrders": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/supplier-portals": { "get": { "tags": [ "Contacts" ], "summary": "Every supplier's portal status — open or closed, and when they last opened it — in one read, with no link minted. The link is minted when somebody copies it, by GET /api/contacts/{id}/supplier-portal.", "operationId": "getApiContactsSupplierPortals", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "contactId": { "type": "string" }, "supplierName": { "type": "string" }, "enabled": { "type": "boolean" }, "lastSeenAt": { "type": "string" } } } }, "example": [ { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "enabled": false, "lastSeenAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{id}/supplier-portal": { "get": { "tags": [ "Contacts" ], "summary": "Whether this supplier is opted in to the supplier portal, and when they last signed in.", "operationId": "getApiContactsByIdSupplierPortal", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsByIdSupplierPortalResponse" }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "enabled": false, "token": "", "url": "https://app.ledgrsa.com/pay/3f1a7c92", "expiresAt": "2026-09-01T09:15:00Z", "lastSeenAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Contacts" ], "summary": "Opt a supplier in and mint their portal credential. Returned once; issuing a new one retires the old.", "operationId": "postApiContactsByIdSupplierPortal", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiContactsByIdCustomerPortalRequest" }, "example": { "enabled": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiContactsByIdSupplierPortalResponse" }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "enabled": true, "token": "", "url": "https://app.ledgrsa.com/pay/3f1a7c92", "expiresAt": "2026-09-01T09:15:00Z", "lastSeenAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{contactId}/transactions": { "get": { "tags": [ "Contacts" ], "summary": "Billable events posted against this contact by an external system, before they are invoiced.", "operationId": "getApiContactsByContactIdTransactions", "description": "Requires the `contacts:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "pending" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiContactsByContactIdTransactionsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiContactsByContactIdTransactionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/{contactId}/transactions/invoice": { "post": { "tags": [ "Contacts" ], "summary": "Roll this contact's pending billable events into a draft invoice.", "operationId": "postApiContactsByContactIdTransactionsInvoice", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsDriversByIdSettleRequest" }, "example": { "from": "2026-08-01", "to": "2026-09-30" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "eventCount": { "type": "integer" }, "total": { "type": "number" }, "currency": { "type": "string" } } } }, "example": [ { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "eventCount": 3, "total": 10005.0, "currency": "ZAR" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "List documents. The reference paginated endpoint: SQL paging plus five child collections batch-loaded by inList. requested=true lists only what customers sent through the ordering portal.", "operationId": "getApiInvoices", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" }, { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "sent" }, { "name": "contactId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "documentType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "invoice" }, { "name": "search", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "requested", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "false" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponse" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "documentType": "invoice", "invoiceNumber": "INV-0001", "status": "sent", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "currency": "ZAR", "exchangeRate": 1.0, "subtotal": 8700.0, "discountTotal": 0.0, "vatTotal": 1305.0, "total": 10005.0, "amountPaid": 0.0, "amountDue": 10005.0, "vatRegistered": true, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "terms": "30", "sourceDocumentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena", "declineReason": "Budget deferred to the next financial year.", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "discountRate": 0.0, "vatRate": 15.0, "vatInclusive": false, "lineSubtotal": 8700.0, "discountAmount": 0.0, "vatAmount": 1305.0, "lineTotal": 10005.0, "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "discountType": "PERCENT", "discountFixed": 0.0, "kind": "PRODUCT", "productCode": "CT-001", "warehouseBin": "A-12-03" } ], "payments": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "amount": 10005.0, "method": "eft", "reference": "INV-0001", "createdAt": "2026-09-01T09:15:00Z" } ], "reminders": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sentDate": "2026-09-01", "channel": "email", "createdAt": "2026-09-01T09:15:00Z" } ], "contactRemindersPaused": false, "tcs": "Goods remain the property of the seller until paid in full.", "bankDetails": "FNB Business Account 62012345678, branch 250655", "footer": "Thank you for your business.", "deposit": { "percent": 15.0, "amount": 10005.0, "appliedTo": "2026-09-30" }, "picking": { "warehouse": "Cape Town HQ", "picker": "Thandi Mokoena", "lines": [ { "idx": 1, "picked": true } ] }, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ], "total": 42, "page": 1, "limit": 50, "totalPages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Invoicing & quotes" ], "summary": "Create any of the ten document types — invoice, quote, proforma, deposit, credit, debit, delivery, purchase_order, receipt, sales_order. A sales_order posts nothing and reserves its tracked lines against stock until it is converted or voided. Send a client-minted id to make the write idempotent for offline replay.", "operationId": "postApiInvoices", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "laybyFeePercent": { "type": "number" }, "retentionPercent": { "type": "number" }, "exportEvidenceReference": { "type": "string" }, "contactId": { "type": "string" }, "companyId": { "type": "string" }, "costCentreId": { "type": "string" }, "analysis2Id": { "type": "string" }, "analysis3Id": { "type": "null" }, "documentType": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "exchangeRate": { "type": "number" }, "paymentTermsDays": { "type": "integer" }, "earlyPaymentDiscountRate": { "type": "number" }, "earlyPaymentDays": { "type": "integer" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "terms": { "type": "string" }, "templateId": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInvoicesRequestLinesItem" } }, "tcs": { "type": "string" }, "bankDetails": { "type": "string" }, "footer": { "type": "string" }, "deposit": { "$ref": "#/components/schemas/PostApiInvoicesRequestDeposit" }, "picking": { "$ref": "#/components/schemas/PostApiInvoicesRequestPicking" }, "allowCreditOverride": { "type": "boolean" }, "sourceDocumentId": { "type": "string" }, "clientId": { "type": "string" }, "documentNumber": { "type": "string" }, "originNodeId": { "type": "string" }, "domesticReverseCharge": { "type": "boolean" }, "forVatCorrection": { "type": "boolean" }, "paymentGateways": { "type": "array", "items": { "type": "string" } }, "deliveryDate": { "type": "string", "format": "date" }, "shipToSiteId": { "type": "null" }, "shipFromLocationId": { "type": "null" }, "customFields": { "$ref": "#/components/schemas/PostApiInvoicesRequestCustomFields" }, "salespersonId": { "type": "null" } } }, "example": { "laybyFeePercent": 0.0, "retentionPercent": 0.0, "exportEvidenceReference": "SAD500 0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis2Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis3Id": null, "documentType": "invoice", "issueDate": "2026-08-10", "dueDate": "2026-09-10", "currency": "ZAR", "exchangeRate": 1.0, "paymentTermsDays": 30, "earlyPaymentDiscountRate": 0.0, "earlyPaymentDays": 30, "reference": "INV-0001", "notes": "Thanks for your business.", "terms": "30", "templateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lines": [ { "description": "Mobile app development", "quantity": 1.0, "unitPrice": 8700.0, "discountRate": 0.0, "discountFixed": 0.0, "discountType": "PERCENT", "vatRate": 15.0, "vatInclusive": false, "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "service", "productCode": "CT-001", "warehouseBin": "A-12-03" } ], "tcs": "Goods remain the property of the seller until paid in full.", "bankDetails": "FNB Business Account 62012345678, branch 250655", "footer": "Thank you for your business.", "deposit": { "percent": 15.0, "amount": 10005.0, "appliedTo": "2026-09-30" }, "picking": { "warehouse": "Cape Town HQ", "picker": "Thandi Mokoena", "lines": [ { "idx": 1, "picked": true } ] }, "allowCreditOverride": false, "sourceDocumentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "originNodeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "domesticReverseCharge": false, "forVatCorrection": false, "paymentGateways": [ "payfast" ], "deliveryDate": "2026-09-01", "shipToSiteId": null, "shipFromLocationId": null, "customFields": {}, "salespersonId": null } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceNumber": { "type": "string" }, "documentType": { "type": "string" }, "status": { "type": "string" }, "subtotal": { "type": "number" }, "vatTotal": { "type": "number" }, "total": { "type": "number" }, "amountPaid": { "type": "number" }, "amountDue": { "type": "number" } } }, "example": { "id": "ed9be4c9-08ee-5ad5-bd0f-a2e2c501fb51", "invoiceNumber": "INV-0042", "documentType": "invoice", "status": "draft", "subtotal": 8700.0, "vatTotal": 1305.0, "total": 10005.0, "amountPaid": 0.0, "amountDue": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "One document with its lines, payments, reminders and attachments.", "operationId": "getApiInvoicesById", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Invoicing & quotes" ], "summary": "Update a document. Note it soft-deletes and re-inserts every line, so anything reading lines for a return must filter deletedAt. A draft credit or debit note takes its original tax invoice in sourceDocumentId; issuing one without it and a reason in notes is refused with a 400, VAT Act s21(3).", "operationId": "putApiInvoicesById", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "laybyFeePercent": { "type": "number" }, "retentionPercent": { "type": "number" }, "exportEvidenceReference": { "type": "string" }, "contactId": { "type": "string" }, "costCentreId": { "type": "string" }, "analysis2Id": { "type": "string" }, "analysis3Id": { "type": "null" }, "sourceDocumentId": { "type": "string" }, "documentType": { "type": "string" }, "declineReason": { "type": "string" }, "status": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "exchangeRate": { "type": "number" }, "paymentTermsDays": { "type": "integer" }, "earlyPaymentDiscountRate": { "type": "number" }, "earlyPaymentDays": { "type": "integer" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "terms": { "type": "string" }, "templateId": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInvoicesRequestLinesItem" } }, "tcs": { "type": "string" }, "bankDetails": { "type": "string" }, "footer": { "type": "string" }, "deposit": { "$ref": "#/components/schemas/PostApiInvoicesRequestDeposit" }, "picking": { "$ref": "#/components/schemas/PostApiInvoicesRequestPicking" }, "domesticReverseCharge": { "type": "boolean" }, "forVatCorrection": { "type": "boolean" }, "paymentGateways": { "type": "array", "items": { "type": "string" } }, "deliveryDate": { "type": "string", "format": "date" }, "shipToSiteId": { "type": "null" }, "shipFromLocationId": { "type": "null" }, "customFields": { "$ref": "#/components/schemas/PostApiInvoicesRequestCustomFields" } } }, "example": { "laybyFeePercent": 0.0, "retentionPercent": 0.0, "exportEvidenceReference": "SAD500 0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis2Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis3Id": null, "sourceDocumentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentType": "invoice", "declineReason": "Budget deferred to the next financial year.", "status": "sent", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "currency": "ZAR", "exchangeRate": 1.0, "paymentTermsDays": 30, "earlyPaymentDiscountRate": 0.0, "earlyPaymentDays": 30, "reference": "INV-0001", "notes": "Updated note.", "terms": "30", "templateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lines": [ { "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "discountRate": 0.0, "discountFixed": 0.0, "discountType": "PERCENT", "vatRate": 15.0, "vatInclusive": false, "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "PRODUCT", "productCode": "CT-001", "warehouseBin": "A-12-03" } ], "tcs": "Goods remain the property of the seller until paid in full.", "bankDetails": "FNB Business Account 62012345678, branch 250655", "footer": "Thank you for your business.", "deposit": { "percent": 15.0, "amount": 10005.0, "appliedTo": "2026-09-30" }, "picking": { "warehouse": "Cape Town HQ", "picker": "Thandi Mokoena", "lines": [ { "idx": 1, "picked": true } ] }, "domesticReverseCharge": true, "forVatCorrection": false, "paymentGateways": [ "payfast" ], "deliveryDate": "2026-09-01", "shipToSiteId": null, "shipFromLocationId": null, "customFields": {} } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Invoicing & quotes" ], "summary": "Void a document. Sets the status; nothing leaves history. An issued tax invoice, credit note or debit note is refused with a 409 naming the note that corrects it.", "operationId": "deleteApiInvoicesById", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiBillsByIdResponse" }, "example": { "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/fulfilment": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "Where a sales order is — Open, On a trip, Part delivered, Delivered or Invoiced — read from its delivery notes and invoices, with what each line still has to deliver.", "operationId": "getApiInvoicesByIdFulfilment", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" }, "label": { "type": "string" }, "ordered": { "type": "number" }, "onATrip": { "type": "number" }, "delivered": { "type": "number" }, "invoiced": { "type": "number" }, "openLines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "open": { "type": "number" }, "unitPrice": { "type": "number" }, "vatRate": { "type": "number" } } } }, "backordered": { "type": "number" } } }, "example": { "state": "sent", "label": "Karoo Fresh Holdings Ltd", "ordered": 1.0, "onATrip": 1.0, "delivered": 1.0, "invoiced": 1.0, "openLines": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "open": 1.0, "unitPrice": 2900.0, "vatRate": 15.0 } ], "backordered": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/summary": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "The KPI row — outstanding, overdue, paid this month, and drafts.", "operationId": "getApiInvoicesSummary", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "outstanding": { "type": "number" }, "overdue": { "type": "number" }, "paid30": { "type": "number" }, "draftTotal": { "type": "number" }, "quotesOpen": { "type": "integer" }, "documentCount": { "type": "integer" } } }, "example": { "outstanding": 1.0, "overdue": 1.0, "paid30": 1.0, "draftTotal": 10005.0, "quotesOpen": 1, "documentCount": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/send": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Mark sent and deliver by email or WhatsApp, with the PDF attached if the tenant's settings say so. Send your own clientId (a UUID) and a retry after a lost response reports the send already made instead of sending it again. A credit or debit note is refused with a 400 until it names its original tax invoice (sourceDocumentId) and a reason (notes), VAT Act s21(3).", "operationId": "postApiInvoicesByIdSend", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string" }, "clientId": { "type": "string" }, "allowCreditOverride": { "type": "boolean" } } }, "example": { "channel": "email", "clientId": "8b2d6f14-3c7a-4e95-b0d2-71a9e5c3f640", "allowCreditOverride": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInvoicesByIdSendResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInvoicesByIdSendResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/bulk-send": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Email several documents at once. Each goes through the single send (a draft is issued, the PDF attached when the settings say so, the delivery recorded on it); a voided document is skipped. Answers what happened to each one. Re-send the same batchId to retry: a document this batch already delivered is not emailed again. Email only; at most 100 documents. Requires invoices:edit.", "operationId": "postApiInvoicesBulkSend", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batchId": { "type": "string" }, "ids": { "type": "array", "items": { "type": "string" } }, "channel": { "type": "string" } } }, "example": { "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ids": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "channel": "email" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "batchId": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "customer": { "type": "string" }, "outcome": { "type": "string" }, "reason": { "type": "string" } } } } } }, "example": { "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "INV-0001", "customer": "Karoo Fresh Holdings Ltd", "outcome": "text", "reason": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/bulk-pdf": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Several documents as ONE PDF, in the order asked for, each starting on its own page — for printing or keeping. Documents not in the active company are left out; the X-Ledgr-Documents-Included header says how many are in it. At most 50. Requires invoices:view.", "operationId": "postApiInvoicesBulkPdf", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInboxReadRequest" }, "example": { "ids": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "201": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/payments": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Record a payment. Moves the document to partial or paid and advances any CRM deal linked to it. A payment above the balance is refused unless keepAsCredit names the excess, to the cent: then the document is settled and the excess is kept as the customer's credit for a later invoice (see apply-credit), and the receipt is banked in full. On an issued credit note the same call records a refund: money paid back to the customer, never more than is still owed back, which moves the credit note to partial or paid (shown as part refunded or refunded) and posts DR trade receivables / CR bank. A draft credit note is refused (issue it first), and a refund cannot keep or spend customer credit. Nothing is sent through a payment gateway.", "operationId": "postApiInvoicesByIdPayments", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" }, "method": { "type": "string" }, "date": { "type": "string", "format": "date" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "clientId": { "type": "string" }, "exchangeRate": { "type": "number" }, "keepAsCredit": { "type": "null" }, "bankAccountId": { "type": "string" } } }, "example": { "amount": 51750.0, "method": "EFT", "date": "2026-08-12", "reference": "FNB 4472", "notes": "Budget deferred to the next financial year.", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "exchangeRate": 1.0, "keepAsCredit": null, "bankAccountId": "8d2e4b17-6c3a-4f90-b5e1-7a9c0d3f2b64" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/payments/{paymentId}": { "delete": { "tags": [ "Invoicing & quotes" ], "summary": "Withdraw a receipt keyed by hand. Reverses it in the ledger, recomputes what the document owes from the surviving payments, and audits at warning. Refused for a Yoco or PayFast receipt (refund through the gateway), a bank-matched one (unmatch the statement line) and an applied deposit (raise a credit note).", "operationId": "deleteApiInvoicesByIdPaymentsByPaymentId", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/customer-credit": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "The credit this invoice's customer holds — money they overpaid on an earlier invoice and chose to keep for the next one, and what is still owed back on their issued credit notes — in this invoice's currency and company, and how much of it this invoice can take (the smaller of the credit and what it still owes; nothing on a document that cannot take a payment).", "operationId": "getApiInvoicesByIdCustomerCredit", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "customerName": { "type": "string" }, "currency": { "type": "string" }, "available": { "type": "number" }, "amountDue": { "type": "number" }, "applicable": { "type": "number" }, "refundable": { "type": "number" } } }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "customerName": "Karoo Fresh Holdings Ltd", "currency": "ZAR", "available": 1.0, "amountDue": 10005.0, "applicable": 1.0, "refundable": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/apply-credit": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Settle part or all of this invoice from the customer's credit. Refused for more than the customer holds in this currency or more than the invoice still owes. Moves no cash: the credit already sits in Trade Receivables, so no bank leg is posted. Spends the oldest credit first; removing the resulting payment line restores the credit. Send your own clientId (a UUID) and a re-sent request applies the credit once. An issued credit note with something still owed back is credit too: applying it lowers what the credit note owes back by the same amount, and removing the application from the invoice gives it back.", "operationId": "postApiInvoicesByIdApplyCredit", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" }, "clientId": { "type": "string" } } }, "example": { "amount": 250.0, "clientId": "c41e9a07-6b2d-4f8e-a3d1-5e70b9c2f816" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInvoicesByIdApplyCreditResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInvoicesByIdApplyCreditResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/customer-credit/refund": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Pay back credit this invoice's customer holds from their own payments (money they overpaid and chose to keep, or paid on account). Posts debit Trade Receivables, credit the bank account named by bankAccountId (the pooled bank when absent) on date, which is never ahead of today and never before the money arrived, and writes a debit line on that account; no sale is reversed and no VAT moves. Pays back the oldest credit first. Refused for more than the customer holds from their payments by that date (a credit note's own credit is refunded on the credit note). Removing the resulting payment line restores the credit. Send your own clientId (a UUID) and a re-sent request pays back once. Needs invoices:edit.", "operationId": "postApiInvoicesByIdCustomerCreditRefund", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" }, "date": { "type": "string", "format": "date" }, "bankAccountId": { "type": "string" }, "reference": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "amount": 350.0, "date": "2026-10-28", "bankAccountId": "8d2e4b17-6c3a-4f90-b5e1-7a9c0d3f2b64", "reference": "Refund EFT", "clientId": "c41e9a07-6b2d-4f8e-a3d1-5e70b9c2f816" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInvoicesByIdApplyCreditResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInvoicesByIdApplyCreditResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/convert": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Convert a quote, pro-forma or sales order into a draft tax invoice with the same lines. Mints the invoice number; the invoice posts and takes its stock when it is issued. Converting a sales order releases what it reserved. A quote or pro-forma can instead be invoiced in parts: send percent (a share of every line) or lines (chosen line ids with quantities); each part is its own draft tax invoice, a part asking for more than is left answers 409 naming the figures, and the quote reads invoiced once nothing is left. With neither field, a part-invoiced quote invoices what is left. A clientId makes the call replay-safe: a retry answers 200 with the invoice the first call raised.", "operationId": "postApiInvoicesByIdConvert", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terms": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "paymentTermsDays": { "type": "integer" }, "clientId": { "type": "string" }, "percent": { "type": "null" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string" }, "quantity": { "type": "number" } } } } } }, "example": { "terms": "30", "dueDate": "2026-09-01", "paymentTermsDays": 30, "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "percent": null, "lines": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 2.0 } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/progress": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "What has been invoiced against a quote or pro-forma: the quote's total, the sum of the live invoices raised from it, each line's quantity invoiced and still to invoice, and the invoices themselves. Voided and deleted invoices give their part back.", "operationId": "getApiInvoicesByIdProgress", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string" }, "quoteNumber": { "type": "string" }, "currency": { "type": "string" }, "quoteTotal": { "type": "number" }, "invoicedTotal": { "type": "number" }, "fullyInvoiced": { "type": "boolean" }, "partlyInvoiced": { "type": "boolean" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string" }, "lineNumber": { "type": "integer" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "invoicedQuantity": { "type": "number" }, "remainingQuantity": { "type": "number" }, "unitPrice": { "type": "number" } } } }, "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceNumber": { "type": "string" }, "status": { "type": "string" }, "total": { "type": "number" }, "issueDate": { "type": "string", "format": "date" } } } } } }, "example": { "quoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quoteNumber": "QUO-0001", "currency": "ZAR", "quoteTotal": 10005.0, "invoicedTotal": 4002.0, "fullyInvoiced": false, "partlyInvoiced": true, "lines": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "quantity": 3.0, "invoicedQuantity": 1.2, "remainingQuantity": 1.8, "unitPrice": 2900.0 } ], "invoices": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "status": "sent", "total": 4002.0, "issueDate": "2026-09-01" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/layby": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "A lay-by's money: its price, what is held (the customer's money until the goods are delivered), what is still owed, the cancellation fee agreed when it was made (at most 1% of the price), what cancelling now would keep and refund, and every payment, application, fee and refund.", "operationId": "getApiInvoicesByIdLayby", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdLaybyResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdLaybyResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/layby/payments": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Take a payment towards an issued lay-by into a bank account. Held in Lay-by Payments Held (2157), never revenue; refused on a draft, past the price, or once collected or cancelled.", "operationId": "postApiInvoicesByIdLaybyPayments", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdLaybyResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdLaybyResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/layby/collect": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Collect a lay-by paid in full: its goods are issued on a tax invoice dated the collection, taken out of stock, and the invoice is settled from what was held. Refused before it is paid in full, and a second time.", "operationId": "postApiInvoicesByIdLaybyCollect", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdLaybyResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdLaybyResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/layby/cancel": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Cancel a lay-by: the agreed fee is kept on its own invoice (unless waived for death or hospitalisation) and the rest is refunded from the bank account given; the goods are released.", "operationId": "postApiInvoicesByIdLaybyCancel", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdLaybyResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdLaybyResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/instalment-credit": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "Every instalment credit agreement of the company, newest delivery first: the customer, the cash price, what is owed today and the next instalment's date.", "operationId": "getApiInvoicesInstalmentCredit", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "customerName": { "type": "string" }, "status": { "type": "string" }, "deliveredOn": { "type": "string", "format": "date" }, "cashPrice": { "type": "number" }, "balance": { "type": "number" }, "nextDueOn": { "type": "string", "format": "date" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "status": "sent", "deliveredOn": "2026-09-01", "cashPrice": 10005.0, "balance": 10005.0, "nextDueOn": "2026-09-01" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/instalment-credit": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "The instalment credit agreement on an invoice: its terms and National Credit Act particulars (cost of credit, total payable, the rate and its regulation 42 cap), the schedule with each month's finance charge, and the statement of account.", "operationId": "getApiInvoicesByIdInstalmentCredit", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdInstalmentCreditResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdInstalmentCreditResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Invoicing & quotes" ], "summary": "Conclude the agreement at delivery: the tax invoice is settled in full - the deposit into the bank account given, the rest financed into Instalment Credit Receivable (1328) - so the VAT on the whole cash value is declared now on either accounting basis (VAT Act s9(3)(c)). Refused on a draft, a foreign-currency invoice or one already paid towards, and above the caps.", "operationId": "postApiInvoicesByIdInstalmentCredit", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdInstalmentCreditResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdInstalmentCreditResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/instalment-credit/quote": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "The pre-agreement quote on an issued tax invoice (National Credit Act s92): the schedule, the cost of credit and the total payable. Nothing is written. A rate above the regulation 42 cap for the credit type (the repo rate plus 17% for an instalment agreement), an initiation fee above regulation 42(2) and 43(3) or a service fee above R60 a month is refused, naming the cap.", "operationId": "postApiInvoicesByIdInstalmentCreditQuote", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "customerName": { "type": "string" }, "deliveredOn": { "type": "string", "format": "date" }, "cashPrice": { "type": "number" }, "vatInCashPrice": { "type": "number" }, "deposit": { "type": "number" }, "principalDebt": { "type": "number" }, "termMonths": { "type": "integer" }, "annualRatePercent": { "type": "number" }, "monthlyRatePercent": { "type": "number" }, "referenceRatePercent": { "type": "number" }, "creditType": { "type": "string" }, "creditTypeLabel": { "type": "string" }, "maximumRatePercent": { "type": "number" }, "initiationFee": { "type": "number" }, "monthlyServiceFee": { "type": "number" }, "instalment": { "type": "number" }, "totalInterest": { "type": "number" }, "totalFees": { "type": "number" }, "costOfCredit": { "type": "number" }, "totalPayable": { "type": "number" }, "schedule": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdInstalmentCreditResponseScheduleItem" } } } }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "deliveredOn": "2026-09-01", "cashPrice": 10005.0, "vatInCashPrice": 1305.0, "deposit": 1.0, "principalDebt": 1.0, "termMonths": 1, "annualRatePercent": 15.0, "monthlyRatePercent": 15.0, "referenceRatePercent": 15.0, "creditType": "standard", "creditTypeLabel": "Karoo Fresh Holdings Ltd", "maximumRatePercent": 15.0, "initiationFee": 1.0, "monthlyServiceFee": 1.0, "instalment": 1.0, "totalInterest": 10005.0, "totalFees": 10005.0, "costOfCredit": 10005.0, "totalPayable": 10005.0, "schedule": [ { "number": 1, "dueOn": "2026-09-01", "instalment": 1.0, "interest": 1.0, "fees": 1.0, "capital": 1.0, "balanceAfter": 10005.0, "charged": false, "chargeNumber": "INV-0001" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/instalment-credit/charges": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Earn every month's finance charge falling due by the date given (today when omitted): the principal outstanding times the monthly rate, on its own exempt document (VAT201 field 3), with the month's service fee beside it at the standard rate.", "operationId": "postApiInvoicesByIdInstalmentCreditCharges", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdInstalmentCreditResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdInstalmentCreditResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/instalment-credit/instalments": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Record an instalment into a bank account: the month's charge is earned first, then the money pays interest, then fees, then the principal (National Credit Act s126(3)). Refused above what is owed today; the agreement reads settled once nothing is.", "operationId": "postApiInvoicesByIdInstalmentCreditInstalments", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdInstalmentCreditResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdInstalmentCreditResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/instalment-credit/write-off": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Write off what is still owed as irrecoverable (VAT Act s22(1)): the cash value not recovered claims back its VAT at the invoice's tax fraction (field 17) and the unpaid charge documents are written off. Refused once the goods are repossessed.", "operationId": "postApiInvoicesByIdInstalmentCreditWriteOff", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdInstalmentCreditResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdInstalmentCreditResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/instalment-credit/repossess": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "The goods repossessed or surrendered (VAT Act s8(10)): the tax fraction of the cash value not recovered (s10(16)) is deducted as input tax (field 15) and the rest of the principal is a loss; count the goods back into stock with a stock adjustment.", "operationId": "postApiInvoicesByIdInstalmentCreditRepossess", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInvoicesByIdInstalmentCreditResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdInstalmentCreditResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/gift-vouchers": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "The company's gift vouchers, newest first, beside the voucher book's total and the ledger's 2159 Gift Vouchers Outstanding with their difference. ?status=active|spent|expired narrows the list.", "operationId": "getApiGiftVouchers", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "active" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "vouchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "faceValue": { "type": "number" }, "balance": { "type": "number" }, "status": { "type": "string" }, "issuedOn": { "type": "string", "format": "date" }, "expiresOn": { "type": "string", "format": "date" }, "contactId": { "type": "string" }, "movements": { "type": "array", "items": { "type": "object" } } } } }, "outstanding": { "type": "number" }, "ledgerBalance": { "type": "number" }, "difference": { "type": "number" } } }, "example": { "vouchers": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "GV-7F3A9C21", "faceValue": 500.0, "balance": 350.0, "status": "active", "issuedOn": "2026-10-01", "expiresOn": "2029-10-01", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "movements": [] } ], "outstanding": 350.0, "ledgerBalance": 350.0, "difference": 0.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Invoicing & quotes" ], "summary": "Sell a face-value gift voucher into a bank account. Held in Gift Vouchers Outstanding (2159) with no VAT and no revenue: the sale is disregarded (VAT Act s10(18)) and the money is the bearer's until it is spent. The term is three years from sale unless longer; a shorter one is refused (Consumer Protection Act s63(2)).", "operationId": "postApiGiftVouchers", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "faceValue": { "type": "number" }, "balance": { "type": "number" }, "status": { "type": "string" }, "issuedOn": { "type": "string", "format": "date" }, "expiresOn": { "type": "string", "format": "date" }, "contactId": { "type": "string" }, "movements": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "amount": { "type": "number" }, "on": { "type": "string", "format": "date" } } } } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "GV-7F3A9C21", "faceValue": 500.0, "balance": 500.0, "status": "active", "issuedOn": "2026-10-01", "expiresOn": "2029-10-01", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "movements": [ { "kind": "issued", "amount": 500.0, "on": "2026-10-01" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/gift-vouchers/{id}": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "One voucher with every movement: sold, spent on which invoice, lapsed.", "operationId": "getApiGiftVouchersById", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiGiftVouchersByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiGiftVouchersByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/gift-vouchers/{id}/redeem": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Spend part or all of a voucher on an issued tax invoice (DR 2159 / CR 1320, no bank leg). The VAT is the invoice's, on its own date - the supply of the goods or services is made now. Refused on a draft or void invoice, past the voucher's balance or the invoice's amount due, and after the voucher's term.", "operationId": "postApiGiftVouchersByIdRedeem", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiGiftVouchersByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiGiftVouchersByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/gift-vouchers/{id}/expire": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Let what is left of a voucher lapse once its term is over: DR 2159 / CR 4140 Sundry Income, with no VAT (no supply was ever made). Refused while the voucher is still good.", "operationId": "postApiGiftVouchersByIdExpire", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiGiftVouchersByIdResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "GV-7F3A9C21", "faceValue": 500.0, "balance": 0.0, "status": "expired", "issuedOn": "2026-10-01", "expiresOn": "2029-10-01", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "movements": [ { "kind": "issued", "amount": 500.0, "on": "2026-10-01" }, { "kind": "redeemed", "amount": 150.0, "on": "2026-10-14", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0042" }, { "kind": "expired", "amount": 350.0, "on": "2029-10-02" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/retention/release": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Release retention held on a contract invoiced from this quote in parts: half of what was withheld at practical completion (stage practical_completion), everything still held at the end of the defects period (stage final), or an explicit amount before VAT. Raised as a draft invoice that charges VAT on the release; more than is held is refused with 400.", "operationId": "postApiInvoicesByIdRetentionRelease", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "documentType": { "type": "string" }, "invoiceNumber": { "type": "string" }, "status": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "deliveryDate": { "type": "string", "format": "date" }, "shipToSiteId": { "type": "string" }, "shipToAddress": { "type": "string" }, "shipFromLocationId": { "type": "string" }, "shipFromReason": { "type": "string" }, "expectedPaymentDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "exchangeRate": { "type": "number" }, "subtotal": { "type": "number" }, "discountTotal": { "type": "number" }, "vatTotal": { "type": "number" }, "total": { "type": "number" }, "amountPaid": { "type": "number" }, "amountDue": { "type": "number" }, "vatRegistered": { "type": "boolean" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "terms": { "type": "string" }, "paymentTermsDays": { "type": "integer" }, "sourceDocumentId": { "type": "string" }, "decidedAt": { "type": "string" }, "decidedByName": { "type": "string" }, "declineReason": { "type": "string" }, "customerFirstViewedAt": { "type": "string" }, "customerLastViewedAt": { "type": "string" }, "requestedByCustomer": { "type": "boolean" }, "internalNote": { "type": "string" }, "lastSendChannel": { "type": "string" }, "lastSendDelivered": { "type": "boolean" }, "lastSendError": { "type": "string" }, "lastSendAt": { "type": "string" }, "costCentreId": { "type": "string" }, "stockWarnings": { "type": "array", "items": { "type": "string" } }, "fulfilment": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdResponseLinesItem" } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "method": { "type": "string" }, "reference": { "type": "string" }, "createdAt": { "type": "string" }, "awaitingBank": { "type": "boolean" } } } }, "reminders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "sentDate": { "type": "string", "format": "date" }, "channel": { "type": "string" }, "createdAt": { "type": "string" }, "status": { "type": "string" }, "deliveryStatus": { "type": "string" } } } }, "contactRemindersPaused": { "type": "boolean" }, "tcs": { "type": "string" }, "bankDetails": { "type": "string" }, "footer": { "type": "string" }, "deposit": { "$ref": "#/components/schemas/PostApiInvoicesRequestDeposit" }, "retentionPercent": { "type": "number" }, "picking": { "$ref": "#/components/schemas/PostApiInvoicesRequestPicking" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "domesticReverseCharge": { "type": "boolean" }, "paymentGateways": { "type": "array", "items": { "type": "string" } }, "changeNotice": { "type": "string" }, "customFields": { "$ref": "#/components/schemas/GetApiPayrollSettingsResponseDesignLabels" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "documentType": "invoice", "invoiceNumber": "INV-0001", "status": "sent", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "deliveryDate": "2026-09-01", "shipToSiteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "shipToAddress": "12 Long Street, Cape Town, 8001", "shipFromLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "shipFromReason": "Budget deferred to the next financial year.", "expectedPaymentDate": "2026-09-01", "currency": "ZAR", "exchangeRate": 1.0, "subtotal": 8700.0, "discountTotal": 0.0, "vatTotal": 1305.0, "total": 10005.0, "amountPaid": 0.0, "amountDue": 10005.0, "vatRegistered": true, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "terms": "30", "paymentTermsDays": 30, "sourceDocumentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena", "declineReason": "Budget deferred to the next financial year.", "customerFirstViewedAt": "2026-09-01T09:15:00Z", "customerLastViewedAt": "2026-09-01T09:15:00Z", "requestedByCustomer": false, "internalNote": "Budget deferred to the next financial year.", "lastSendChannel": "email", "lastSendDelivered": true, "lastSendError": "text", "lastSendAt": "2026-09-01T09:15:00Z", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stockWarnings": [ "text" ], "fulfilment": "text", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "discountRate": 0.0, "vatRate": 15.0, "vatInclusive": false, "lineSubtotal": 8700.0, "discountAmount": 0.0, "vatAmount": 1305.0, "lineTotal": 10005.0, "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "discountType": "PERCENT", "discountFixed": 0.0, "kind": "PRODUCT", "productCode": "CT-001", "warehouseBin": "A-12-03" } ], "payments": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "amount": 10005.0, "method": "eft", "reference": "INV-0001", "createdAt": "2026-09-01T09:15:00Z", "awaitingBank": false } ], "reminders": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sentDate": "2026-09-01", "channel": "email", "createdAt": "2026-09-01T09:15:00Z", "status": "sent", "deliveryStatus": "sent" } ], "contactRemindersPaused": false, "tcs": "Goods remain the property of the seller until paid in full.", "bankDetails": "FNB Business Account 62012345678, branch 250655", "footer": "Thank you for your business.", "deposit": { "percent": 15.0, "amount": 10005.0, "appliedTo": "2026-09-30" }, "retentionPercent": 15.0, "picking": { "warehouse": "Cape Town HQ", "picker": "Thandi Mokoena", "lines": [ { "idx": 1, "picked": true } ] }, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "domesticReverseCharge": false, "paymentGateways": [ "payfast" ], "changeNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "customFields": { "key": "text" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/apply-deposit": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Apply a deposit invoice against the final invoice, releasing it from Deferred Revenue (2150).", "operationId": "postApiInvoicesByIdApplyDeposit", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInvoicesByIdApplyDepositRequest" }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "depositId": { "type": "string" }, "depositAppliedTo": { "type": "string", "format": "date" }, "invoiceId": { "type": "string" }, "newInvoiceStatus": { "type": "string" }, "amount": { "type": "number" } } }, "example": { "depositId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "depositAppliedTo": "2026-09-30", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "newInvoiceStatus": "sent", "amount": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/reminders": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Send a payment reminder now, outside the configured schedule. Send your own clientId (a UUID) and a retry after a lost response reports the reminder already sent instead of sending it again.", "operationId": "postApiInvoicesByIdReminders", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "channel": "email", "clientId": "c41e9a07-6b2d-4f8e-a3d1-5e70b9c2f816" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInvoicesByIdSendResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInvoicesByIdSendResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/bad-debts": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Write a debt off as bad, or record a recovery of one, on the invoice itself — on every plan with Invoicing. `bad_debt_written_off` writes `amount` (at most the amount due) off: DR 6300 Bad debts / CR 1320, and only when the company is a VAT vendor on `date` and the invoice charged VAT is the invoice's own VAT share claimed back as well (DR 1340, VAT201 field 17); a company that is not a vendor claims nothing (`vatAmount` 0). Needs invoices:approve and is audited as `invoice.bad_debt_written_off`. `bad_debt_recovered` reinstates up to what was written off (DR 1320 / CR 6300, and CR 2130 at the same fraction only where the write-off claimed VAT) so the customer's payment is then recorded as usual; needs invoices:edit. A blank reason, more than is owed or written off, and a vendor's debt on the payments basis are refused.", "operationId": "postApiInvoicesByIdBadDebts", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "amount": { "type": "number" }, "date": { "type": "string", "format": "date" }, "reason": { "type": "string" }, "documentRef": { "type": "string" } } }, "example": { "kind": "bad_debt_written_off", "amount": 11500.0, "date": "2026-09-30", "reason": "Customer liquidated; claim lodged with the liquidator", "documentRef": "Liquidator's letter 2026/118" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "kindLabel": { "type": "string" }, "field": { "type": "string" }, "date": { "type": "string", "format": "date" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "consideration": { "type": "number" }, "vatAmount": { "type": "number" }, "reason": { "type": "string" }, "documentRef": { "type": "string" } } }, "example": { "id": "7f6c1a2e-0000-4000-8000-000000000001", "kind": "bad_debt_written_off", "kindLabel": "Bad debt written off", "field": "17", "date": "2026-09-30", "invoiceId": "7f6c1a2e-0000-4000-8000-000000000002", "invoiceNumber": "INV-0042", "consideration": 11500.0, "vatAmount": 1500.0, "reason": "Customer liquidated; claim lodged with the liquidator", "documentRef": "Liquidator's letter 2026/118" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/expected-payment-date": { "put": { "tags": [ "Invoicing & quotes" ], "summary": "Record the date the customer has promised to pay, or send null to clear it. The cash-flow forecast places an overdue invoice on this date instead of leaving it out — but only while the date is today or later, so a promise that has come and gone falls back to the due date. Nothing is ever inferred: an invoice with no promise stays in the overdue figure reported beside the forecast. Writes one column and nothing else, so no line is rewritten and no journal is re-posted.", "operationId": "putApiInvoicesByIdExpectedPaymentDate", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedPaymentDate": { "type": "string", "format": "date" } } }, "example": { "expectedPaymentDate": "2026-10-15" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceNumber": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "expectedPaymentDate": { "type": "string", "format": "date" }, "forecastDate": { "type": "string", "format": "date" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "dueDate": "2026-09-01", "expectedPaymentDate": "2026-10-15", "forecastDate": "2026-10-15" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/payment-links": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "Payment links already minted for this document.", "operationId": "getApiInvoicesByIdPaymentLinks", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "gateway": { "type": "string" }, "url": { "type": "string" }, "amountCents": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "type": "string" }, "paidAt": { "type": "string" }, "createdAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "gateway": "payfast", "url": "https://app.ledgrsa.com/pay/3f1a7c92", "amountCents": 49900, "currency": "ZAR", "status": "sent", "expiresAt": "2026-09-01T09:15:00Z", "paidAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Invoicing & quotes" ], "summary": "Mint a Ledgr /pay/{linkId} URL that builds and signs a PayFast checkout at request time. PayFast only — Yoco is refused, because it has no server-side call to obtain a checkout.", "operationId": "postApiInvoicesByIdPaymentLinks", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gateway": { "type": "string" }, "amountCents": { "type": "integer" }, "expiresAt": { "type": "string" } } }, "example": { "gateway": "payfast", "amountCents": 49900, "expiresAt": "2026-09-01T09:15:00Z" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "gateway": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" } } }, "example": { "id": "acc6ca52-1ef9-5d6e-8638-5a7c33f1f3dc", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "gateway": "payfast", "url": "https://www.ledgrsa.com/pay/", "status": "pending", "expiresAt": "2026-09-10T00:00:00Z", "createdAt": "2026-09-01T09:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/pdf": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Render a document to PDF server-side, from the same HTML the preview and the portal use.", "operationId": "postApiInvoicesPdf", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "earlyPaymentDiscountRate": { "type": "number" }, "earlyPaymentBy": { "type": "string", "format": "date" }, "docType": { "type": "string" }, "docTitle": { "type": "string" }, "number": { "type": "string" }, "date": { "type": "string", "format": "date" }, "due": { "type": "string", "format": "date" }, "status": { "type": "string" }, "customerReference": { "type": "string" }, "originalNumber": { "type": "string" }, "originalDate": { "type": "string", "format": "date" }, "vatRegistered": { "type": "boolean" }, "currencyCode": { "type": "string" }, "currencySymbol": { "type": "string" }, "sender": { "$ref": "#/components/schemas/PostApiInvoicesPdfRequestClient" }, "client": { "$ref": "#/components/schemas/PostApiInvoicesPdfRequestClient" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "code": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "discount": { "type": "number" }, "discountIsPercent": { "type": "boolean" }, "vatPercent": { "type": "number" }, "lineTotal": { "type": "number" }, "kind": { "type": "string" }, "unit": { "type": "string" } } } }, "subtotal": { "type": "number" }, "discountTotal": { "type": "number" }, "vatTotal": { "type": "number" }, "total": { "type": "number" }, "notes": { "type": "string" }, "tcs": { "type": "string" }, "bankDetails": { "type": "string" }, "footer": { "type": "string" }, "templateColorHex": { "type": "string" }, "primaryLogoSrc": { "type": "string" }, "associationLogoSrc": { "type": "string" }, "show": { "type": "object", "properties": { "dueDate": { "type": "boolean" }, "contactName": { "type": "boolean" }, "businessAddress": { "type": "boolean" }, "vatNumber": { "type": "boolean" }, "discountColumn": { "type": "boolean" }, "associationLogo": { "type": "boolean" }, "paymentLinks": { "type": "boolean" } } }, "labels": { "type": "object", "properties": { "description": { "type": "string" }, "qty": { "type": "string" }, "rate": { "type": "string" }, "discount": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" }, "hours": { "type": "string" }, "grandTotal": { "type": "string" } } }, "depositPercent": { "type": "number" }, "depositAmount": { "type": "number" }, "paymentGateways": { "type": "array", "items": { "type": "string" } }, "amountPaid": { "type": "number" }, "amountDue": { "type": "number" }, "paidDeposits": { "type": "array", "items": { "type": "object" } }, "depositVat": { "$ref": "#/components/schemas/PostApiInvoicesRequestCustomFields" }, "paymentMethod": { "type": "string" }, "paymentDate": { "type": "string", "format": "date" }, "domesticReverseCharge": { "type": "boolean" }, "randFigures": { "type": "null" }, "formats": { "type": "object", "properties": { "date": { "type": "string" }, "number": { "type": "string" } } }, "invoiceId": { "type": "string" }, "workSignOff": { "type": "object", "properties": { "jobNumber": { "type": "string" }, "signedBy": { "type": "string" }, "role": { "type": "string" }, "signedOn": { "type": "string", "format": "date" }, "signatureSrc": { "type": "string" } } }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } } }, "language": { "type": "string" } } }, "example": { "earlyPaymentDiscountRate": 2.0, "earlyPaymentBy": "2026-10-24", "docType": "invoice", "docTitle": "Karoo Fresh Holdings Ltd", "number": "INV-0001", "date": "2026-09-30", "due": "2026-10-31", "status": "sent", "customerReference": "PO-4471", "originalNumber": "INV-0042", "originalDate": "2026-08-14", "vatRegistered": true, "currencyCode": "ZAR", "currencySymbol": "R", "sender": { "name": "Karoo Fresh Holdings Ltd", "address": "12 Long Street, Cape Town, 8001", "vatNumber": "4123456789", "email": "accounts@karoofresh.example", "registrationNumber": "2021/123456/07" }, "client": { "name": "Karoo Fresh Holdings Ltd", "address": "12 Long Street, Cape Town, 8001", "vatNumber": "4123456789", "email": "accounts@karoofresh.example", "registrationNumber": "2021/123456/07" }, "lines": [ { "description": "Captured during the August review", "code": "CT-001", "quantity": 2.0, "unitPrice": 1500.0, "discount": 0.0, "discountIsPercent": true, "vatPercent": 15.0, "lineTotal": 1500.0, "kind": "PRODUCT", "unit": "each" } ], "subtotal": 1500.0, "discountTotal": 0.0, "vatTotal": 15.0, "total": 1500.0, "notes": "Budget deferred to the next financial year.", "tcs": "Goods remain the property of the seller until paid in full.", "bankDetails": "FNB Business Account 62012345678, branch 250655", "footer": "Thank you for your business.", "templateColorHex": "#0D47A1", "primaryLogoSrc": "https://app.ledgrsa.com/files/logo.png", "associationLogoSrc": "https://app.ledgrsa.com/files/association.png", "show": { "dueDate": true, "contactName": true, "businessAddress": true, "vatNumber": true, "discountColumn": true, "associationLogo": true, "paymentLinks": true }, "labels": { "description": "Description", "qty": "Qty", "rate": "Rate", "discount": "Discount", "tax": "VAT", "total": "Total", "hours": "Hours", "grandTotal": "R 1 150.00" }, "depositPercent": 15.0, "depositAmount": 10005.0, "paymentGateways": [ "payfast" ], "amountPaid": 0.0, "amountDue": 1500.0, "paidDeposits": [], "depositVat": {}, "paymentMethod": "eft", "paymentDate": "2026-09-01", "domesticReverseCharge": false, "randFigures": null, "formats": { "date": "DAY_MONTH_YEAR", "number": "SPACE_POINT" }, "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workSignOff": { "jobNumber": "JC-0001", "signedBy": "Thandi Mokoena", "role": "Accountant", "signedOn": "2026-09-01", "signatureSrc": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==" }, "customFields": [ { "label": "Site reference", "value": "Sandton Gate, Block C" } ], "language": "af" } } } }, "responses": { "201": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/property-sales": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "The company's sales of fixed property (T-7.20): each with its VAT treatment, its s9(3)(d) time of supply and rate, its payments and the output tax each declared. Needs invoices:view.", "operationId": "getApiPropertySales", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sales": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPropertySalesResponse" } } } }, "example": { "sales": [ { "id": "7f6c1a2e-0000-4000-8000-000000000020", "property": "Erf 412, Stellenbosch", "buyer": "T Mokoena", "agreementDate": "2026-08-01", "price": 1150000.0, "treatment": "vat", "treatmentNote": "A taxable supply by a VAT vendor: VAT is charged and the buyer pays no transfer duty (Transfer Duty Act s9(15)).", "heldAs": "stock", "fixedAssetId": null, "capitalGoods": false, "residentialPriceFixed": false, "timeOfSupply": "2026-08-15", "ratePercent": 15.0, "rateReason": "s9(3)(d): the rate on the time of supply", "registeredOn": null, "payments": [ { "id": "7f6c1a2e-0000-4000-8000-000000000021", "paidOn": "2026-08-15", "amount": 115000.0, "heldInTrust": false, "declaredOn": "2026-08-15", "vatAmount": 15000.0 } ], "received": 115000.0, "vatDeclared": 15000.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Invoicing & quotes" ], "summary": "Record the written agreement of a sale of fixed property. A VAT vendor's sale is a taxable supply (no transfer duty, Transfer Duty Act s9(15)); a seller that is not a vendor on the agreement date charges no VAT and the buyer pays transfer duty; `goingConcern` zero-rates an enterprise sold as a going concern only when all five s11(1)(e) terms are true. `heldAs` stock names the account carrying the property's cost and that cost; asset names the fixed asset. `residentialPriceFixed` is the s67A(4) answer. Needs invoices:create.", "operationId": "postApiPropertySales", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "property": { "type": "string" }, "buyer": { "type": "string" }, "agreementDate": { "type": "string", "format": "date" }, "price": { "type": "number" }, "heldAs": { "type": "string" }, "fixedAssetId": { "type": "null" }, "stockAccountCode": { "type": "string" }, "costOfSale": { "type": "number" }, "residentialPriceFixed": { "type": "boolean" }, "goingConcern": { "type": "null" } } }, "example": { "clientId": "7f6c1a2e-0000-4000-8000-000000000020", "property": "Erf 412, Stellenbosch", "buyer": "T Mokoena", "agreementDate": "2026-08-01", "price": 1150000.0, "heldAs": "stock", "fixedAssetId": null, "stockAccountCode": "1395", "costOfSale": 800000.0, "residentialPriceFixed": false, "goingConcern": null } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPropertySalesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPropertySalesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/property-sales/{id}": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "One sale of fixed property, its payments and the output tax declared. Needs invoices:view.", "operationId": "getApiPropertySalesById", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPropertySalesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPropertySalesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/property-sales/{id}/payments": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "A payment of the price. The first payment the seller can apply is the time of supply (s9(3)(d)) and fixes the rate (s67A); its tax fraction is declared in the period it is received (s16(4), VAT404 4.5.2): DR bank, CR 2130, CR 2150. Money a conveyancer or agent holds in trust (`heldInTrust`) is not yet a payment and is declared when paid over on registration. Refused above the price or after registration. Needs invoices:edit.", "operationId": "postApiPropertySalesByIdPayments", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "paidOn": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "heldInTrust": { "type": "boolean" } } }, "example": { "clientId": "7f6c1a2e-0000-4000-8000-000000000021", "paidOn": "2026-08-15", "amount": 115000.0, "heldInTrust": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPropertySalesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPropertySalesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/property-sales/{id}/registration": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Transfer registered in the Deeds Office, with `balancePaid` the rest of the price paid over then (money held in trust included; the whole price must then be paid). Settles the rate with s67A(2), declares the tax still owed, recognises the price less its VAT as revenue (sales 4010 against the cost of sale for stock; profit or loss on disposal for a fixed asset, which leaves the register) and declares it in VAT201 fields 1/4 (1A/4A for a fixed asset, field 2 for a going concern). Needs invoices:edit.", "operationId": "postApiPropertySalesByIdRegistration", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "registeredOn": { "type": "string", "format": "date" }, "balancePaid": { "type": "number" } } }, "example": { "registeredOn": "2026-10-20", "balancePaid": 1035000.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPropertySalesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPropertySalesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/number-leases": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "Document-number leases this device holds, so that a device can mint real series numbers offline; DocumentNumbering still uses its own local lease and never asks for one.", "operationId": "getApiInvoicesNumberLeases", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "docType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "invoice" }, { "name": "nodeId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInvoicesNumberLeasesResponse" } }, "example": [ { "leaseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "docType": "standard", "nodeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "prefix": "INV-", "year": 2026, "padLength": 3, "rangeStart": 1, "rangeEnd": 1, "nextLocal": 1, "issuedAt": "2026-09-01T09:15:00Z", "expiresAt": "2026-09-01T09:15:00Z", "status": "sent", "firstNumber": "INV-0001", "lastNumber": "INV-0001" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Invoicing & quotes" ], "summary": "Reserve a block of numbers in a series.", "operationId": "postApiInvoicesNumberLeases", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "docType": { "type": "string" }, "nodeId": { "type": "string" }, "size": { "type": "integer" } } }, "example": { "docType": "invoice", "nodeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "size": 25 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInvoicesNumberLeasesResponse" }, "example": { "leaseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "docType": "standard", "nodeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "prefix": "INV-", "year": 2026, "padLength": 3, "rangeStart": 1, "rangeEnd": 1, "nextLocal": 1, "issuedAt": "2026-09-01T09:15:00Z", "expiresAt": "2026-09-01T09:15:00Z", "status": "sent", "firstNumber": "INV-0001", "lastNumber": "INV-0001" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/number-leases/release": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Give an unused block back so the numbers are not burned.", "operationId": "postApiInvoicesNumberLeasesRelease", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "docType": { "type": "string" }, "nodeId": { "type": "string" } } }, "example": { "docType": "invoice", "nodeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "released": { "type": "integer" } } }, "example": { "released": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/recurring": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "Recurring invoice schedules.", "operationId": "getApiRecurring", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRecurringResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "amount": 10005.0, "frequency": "monthly", "nextDate": "2026-09-01", "active": true, "currency": "ZAR", "documentType": "invoice", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "onCreate": "email" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Invoicing & quotes" ], "summary": "Create a recurring schedule from a template document.", "operationId": "postApiRecurring", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collectAutomatically": { "type": "boolean" }, "billsAhead": { "type": "boolean" }, "contactId": { "type": "string" }, "documentType": { "type": "string" }, "description": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "number" }, "frequency": { "type": "string" }, "nextDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "paymentTermsDays": { "type": "integer" }, "notes": { "type": "string" }, "terms": { "type": "string" }, "clientId": { "type": "string" }, "onCreate": { "type": "string" }, "vatType": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRecurringRequestLinesItem" } }, "costCentreId": { "type": "string" }, "analysis2Id": { "type": "string" }, "analysis3Id": { "type": "string" }, "tcs": { "type": "string" }, "bankDetails": { "type": "string" }, "footer": { "type": "string" } } }, "example": { "collectAutomatically": false, "billsAhead": false, "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentType": "invoice", "description": "Captured during the August review", "currency": "ZAR", "amount": 1500.0, "frequency": "monthly", "nextDate": "2026-09-30", "endDate": "2026-09-30", "paymentTermsDays": 30, "notes": "Budget deferred to the next financial year.", "terms": "30", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "onCreate": "email", "vatType": "exempt", "lines": [ { "description": "Office cleaning", "quantity": 3.0, "unitPrice": 200.0, "discountRate": 10.0, "discountType": "PERCENT", "vatRate": 15.0, "kind": "SERVICE", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "description": "Delivery of consumables", "quantity": 1.0, "unitPrice": 100.0, "vatRate": 0.0, "vatType": "zero_local" } ], "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis2Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis3Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tcs": "Payable within 30 days.", "bankDetails": "FNB Cheque 62812345678", "footer": "Thank you for your business" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRecurringResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRecurringResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/recurring/{id}": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "One schedule and its issue history.", "operationId": "getApiRecurringById", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "documentType": { "type": "string" }, "description": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "number" }, "frequency": { "type": "string" }, "nextDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "paymentTermsDays": { "type": "integer" }, "notes": { "type": "string" }, "terms": { "type": "string" }, "active": { "type": "boolean" }, "lastGeneratedAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "onCreate": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "documentType": "invoice", "description": "Consulting services — August 2026", "currency": "ZAR", "amount": 10005.0, "frequency": "monthly", "nextDate": "2026-09-01", "endDate": "2026-09-30", "paymentTermsDays": 30, "notes": "Budget deferred to the next financial year.", "terms": "30", "active": true, "lastGeneratedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "onCreate": "email" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Invoicing & quotes" ], "summary": "Change a schedule.", "operationId": "putApiRecurringById", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collectAutomatically": { "type": "boolean" }, "billsAhead": { "type": "boolean" }, "contactId": { "type": "string" }, "description": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "number" }, "frequency": { "type": "string" }, "nextDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "paymentTermsDays": { "type": "integer" }, "notes": { "type": "string" }, "terms": { "type": "string" }, "active": { "type": "boolean" }, "onCreate": { "type": "string" }, "vatType": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRecurringRequestLinesItem" } }, "costCentreId": { "type": "string" }, "analysis2Id": { "type": "string" }, "analysis3Id": { "type": "string" }, "tcs": { "type": "string" }, "bankDetails": { "type": "string" }, "footer": { "type": "string" } } }, "example": { "collectAutomatically": false, "billsAhead": false, "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "currency": "ZAR", "amount": 10005.0, "frequency": "quarterly", "nextDate": "2026-09-01", "endDate": "2026-09-30", "paymentTermsDays": 30, "notes": "Budget deferred to the next financial year.", "terms": "30", "active": true, "onCreate": "email", "vatType": "exempt", "lines": [ { "description": "Office cleaning", "quantity": 3.0, "unitPrice": 200.0, "discountRate": 10.0, "discountType": "PERCENT", "vatRate": 15.0, "kind": "SERVICE", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "description": "Delivery of consumables", "quantity": 1.0, "unitPrice": 100.0, "vatRate": 0.0, "vatType": "zero_local" } ], "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis2Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis3Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tcs": "Payable within 30 days.", "bankDetails": "FNB Cheque 62812345678", "footer": "Thank you for your business" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRecurringResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRecurringResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Invoicing & quotes" ], "summary": "Delete a schedule. Documents it has already raised are untouched.", "operationId": "deleteApiRecurringById", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/recurring/{id}/toggle": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Pause or resume a schedule.", "operationId": "postApiRecurringByIdToggle", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" } } }, "example": { "active": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRecurringResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRecurringResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/recurring/{id}/advance": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Skip a cycle: move the schedule one cycle on WITHOUT raising its document, stepped from its anchor exactly as the scheduled run steps it. The anchor never moves, so a schedule on the 31st that lands on 28 February is back on the 31st in March. To raise the cycle's document and move on, use POST /api/recurring/{id}/run.", "operationId": "postApiRecurringByIdAdvance", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRecurringResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRecurringResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/recurring/{id}/run": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Run now: raise this cycle's document exactly as the scheduled run raises it — the schedule's own amount (VAT-inclusive), document type, payment terms and notes — and move the schedule one cycle on, in one transaction. Refused with 409 on a paused schedule or one another run has just moved on, and with the Free-plan quota's 403 when the month's allowance is used.", "operationId": "postApiRecurringByIdRun", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/PostApiRecurringResponse" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "sentBy": { "type": "string" }, "delivered": { "type": "boolean" } } }, "example": { "schedule": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "amount": 10005.0, "frequency": "monthly", "nextDate": "2026-10-01", "active": true, "currency": "ZAR", "documentType": "invoice", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "onCreate": "email" }, "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0042", "sentBy": "email", "delivered": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoice-templates": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "The tenant's templates plus the five presets. A template is a name and an accent colour — the layout is fixed and there is exactly one.", "operationId": "getApiInvoiceTemplates", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInvoiceTemplatesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "primaryColour": "#0D47A1" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Invoicing & quotes" ], "summary": "Add a template. Only name and colour are accepted; the legacy layout_json, secondary_colour, show_logo, show_signature and footer_text columns are read by nothing and no longer accepted.", "operationId": "postApiInvoiceTemplates", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInvoiceTemplatesRequest" }, "example": { "name": "Site works", "isDefault": false, "primaryColour": "#00838F" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInvoiceTemplatesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "primaryColour": "#0D47A1" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoice-templates/{id}": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "One template.", "operationId": "getApiInvoiceTemplatesById", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "primaryColour": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "isDefault": true, "primaryColour": "#0D47A1", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Invoicing & quotes" ], "summary": "Rename or recolour a template.", "operationId": "putApiInvoiceTemplatesById", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInvoiceTemplatesRequest" }, "example": { "name": "Site works", "isDefault": true, "primaryColour": "#0D47A1" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInvoiceTemplatesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "primaryColour": "#0D47A1" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Invoicing & quotes" ], "summary": "Remove a tenant template. The five presets cannot be removed.", "operationId": "deleteApiInvoiceTemplatesById", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoice-settings": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "The seven-tab settings centre — numbering, labels, field visibility, email templates, branding, defaults and auto-reconciliation.", "operationId": "getApiInvoiceSettings", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequest" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoiceSettingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Invoicing & quotes" ], "summary": "Replace the invoice settings.", "operationId": "putApiInvoiceSettings", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequest" }, "example": { "numbering": { "invoice": { "prefix": "INV-", "next": 1 } }, "labels": { "docTitle": { "invoice": "Tax Invoice" }, "description": "Description", "qty": "Qty", "unitPrice": "Unit price", "rate": "Rate", "hours": "Hours", "discount": "Discount", "tax": "VAT", "net": "Net", "total": "Total" }, "show": { "dueDate": true, "contactName": true, "businessAddress": true, "vatNumber": true, "discountColumn": true, "paymentLinks": true, "associationLogo": true }, "email": { "replyTo": "2026-09-30", "ccSelf": true, "attachPdf": true, "templates": { "invoice": { "subject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached." } } }, "logos": { "primaryName": "Karoo Fresh Holdings Ltd", "primaryDataUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "primaryAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "associationName": "Karoo Fresh Holdings Ltd", "associationDataUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "associationAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, "defaults": { "bankDetails": "", "footer": "", "terms": "Payment within 30 days.", "notes": "" }, "autoRecon": { "enabled": true, "yoco": false, "payfast": true, "matchToleranceZar": 2.0 }, "activeTemplateName": "Site works" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiInvoiceSettingsRequest" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoiceSettingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoice-settings/logo": { "post": { "tags": [ "Invoicing & quotes" ], "summary": "Upload a company or association logo. Raw image bytes with ?slot=primary|association; the server recompresses, stores it in Cloud Storage and files the attachment id against the tenant's settings, so nothing needs saving afterwards.", "operationId": "postApiInvoiceSettingsLogo", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slot", "in": "query", "required": false, "schema": { "type": "string" }, "example": "primary" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "example": "logo.png" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "slot": { "type": "string" }, "attachmentId": { "type": "string" }, "url": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" } } }, "example": { "slot": "text", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "url": "https://app.ledgrsa.com/pay/3f1a7c92", "contentType": "application/pdf", "sizeBytes": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoice-settings/custom-fields": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "The active company's own document fields (at most ten), in order: a label, the document types it is offered on, and whether it prints on the customer's copy. Requires invoices:view.", "operationId": "getApiInvoiceSettingsCustomFields", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiInvoiceSettingsCustomFieldsRequest" }, "example": { "fields": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "docTypes": [ "standard" ], "onCustomerCopy": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Invoicing & quotes" ], "summary": "Replace the active company's own document fields. A field with a blank id is new; a known id keeps its values on documents; a field left out is no longer offered but still prints on documents that carry it. Refused by name: more than ten, a blank or duplicate name, a name over 40 characters, no document type. Requires invoices:edit.", "operationId": "putApiInvoiceSettingsCustomFields", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiInvoiceSettingsCustomFieldsRequest" }, "example": { "fields": [ { "id": "", "label": "Site reference", "docTypes": [ "invoice", "quote" ], "onCustomerCopy": true } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiInvoiceSettingsCustomFieldsRequest" }, "example": { "fields": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "docTypes": [ "standard" ], "onCustomerCopy": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/document-sequences": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "The prefix and next number for each of the nine document types.", "operationId": "getApiDocumentSequences", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiDocumentSequencesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "docType": "invoice", "prefix": "INV-", "includeYear": true, "nextNumber": 1, "padLength": 1, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Invoicing & quotes" ], "summary": "Change a prefix or a starting number. A number already issued is never reissued.", "operationId": "putApiDocumentSequences", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "docType": { "type": "string" }, "prefix": { "type": "string" }, "includeYear": { "type": "boolean" }, "nextNumber": { "type": "integer" }, "padLength": { "type": "integer" } } }, "example": { "docType": "invoice", "prefix": "REF-0042", "includeYear": true, "nextNumber": 1001, "padLength": 3 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiDocumentSequencesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "docType": "invoice", "prefix": "INV-", "includeYear": true, "nextNumber": 1, "padLength": 1, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reminder-configs": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "The automated reminder schedule — how many days before and after due, and on which channel.", "operationId": "getApiReminderConfigs", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReminderConfigsResponse" }, "example": { "enabled": true, "steps": [ { "days": 30, "email": true, "whatsapp": false } ], "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Invoicing & quotes" ], "summary": "Change the reminder schedule. Interest on overdue accounts is held to the National Credit Act's 2% a month (24% a year) unless interestDebtorsAreNotConsumers says none of the business's customers on credit is a consumer under the Act; it is stated to the customer as a monthly rate.", "operationId": "putApiReminderConfigs", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "interestEnabled": { "type": "boolean" }, "interestAnnualRatePercent": { "type": "number" }, "interestDebtorsAreNotConsumers": { "type": "boolean" }, "enabled": { "type": "boolean" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiReminderConfigsRequestStepsItem" } }, "message": { "type": "string" } } }, "example": { "interestEnabled": false, "interestAnnualRatePercent": 0.0, "interestDebtorsAreNotConsumers": false, "enabled": true, "steps": [ { "days": 3, "email": true, "whatsapp": true }, { "days": 7, "email": true, "whatsapp": false }, { "days": 14, "email": true, "whatsapp": false } ], "message": "" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReminderConfigsResponse" }, "example": { "enabled": true, "steps": [ { "days": 30, "email": true, "whatsapp": false } ], "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/attachments": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "Files filed against a sales document — the customer's signed purchase order, a site drawing, a spec sheet. The bytes are not in the response: fetch each `attachmentId` through GET /api/files/{id}, which returns a signed URL as JSON.", "operationId": "getApiInvoicesByIdAttachments", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdAttachmentsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Invoicing & quotes" ], "summary": "Attach a file. RAW BYTES as the body, not multipart and not base64 — base64 inflates a 4 MB scan by a third on exactly the connection this product is designed for. Ten per document, 15 MB each, closed type list (see InvoiceAttachmentPolicy). Not sent to the customer unless “Send with the document” is ticked (PUT …/attachments/{attachmentId}).", "operationId": "postApiInvoicesByIdAttachments", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "filename", "in": "query", "required": false, "description": "The name to give the downloaded file.", "schema": { "type": "string" }, "example": "SignedPO-4417.pdf" }, { "name": "contentType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "application/pdf" }, { "name": "caption", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Serial%20plate%20before%20fitting" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdAttachmentsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/{id}/attachments/{attachmentId}": { "put": { "tags": [ "Invoicing & quotes" ], "summary": "Tick or untick “Send with the document”. Off by default: a ticked file goes on the email beside the document's PDF and is listed on the customer's portal page; an unticked one never leaves the business. Ticking a file that would take the ticked files past 10 MB — what one email can carry — is refused with 400 and a sentence. Returns the document's files.", "operationId": "putApiInvoicesByIdAttachmentsByAttachmentId", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sendWithDocument": { "type": "boolean" } } }, "example": { "sendWithDocument": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdAttachmentsResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "filename": "SignedPO-4417.pdf", "caption": "Serial plate before fitting", "contentType": "application/pdf", "sizeBytes": 1, "sequence": 1, "uploadedByName": "Karoo Fresh Holdings Ltd", "createdAt": "2026-09-01T09:15:00Z", "sendWithDocument": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Invoicing & quotes" ], "summary": "Unlink a file from the document. The stored object is NOT destroyed — an invoicing screen is not where evidence behind a disputed invoice should be shreddable.", "operationId": "deleteApiInvoicesByIdAttachmentsByAttachmentId", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInvoicesByIdAttachmentsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiInvoicesByIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payment-gateways": { "get": { "tags": [ "Payments & gateways" ], "summary": "Which gateways can actually take a payment on this deployment. The single source of truth both sides read — the client greys the rest out rather than offering a dead link.", "operationId": "getApiPaymentGateways", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "available": { "type": "boolean" }, "reason": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "available": true, "reason": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payment-gateways/payfast/credentials": { "get": { "tags": [ "Payments & gateways" ], "summary": "The tenant's PayFast merchant details. The key is write-only and comes back only as a masked hint. Read is gated on invoices:view.", "operationId": "getApiPaymentGatewaysPayfastCredentials", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPaymentGatewaysPayfastCredentialsResponse" }, "example": { "configured": false, "source": "referral", "merchantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "merchantKeyHint": "text", "hasPassphrase": false, "sandbox": true, "active": true, "companyScoped": false, "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Payments & gateways" ], "summary": "Store PayFast merchant credentials, encrypted with SecretBox. Gated on roles:edit, the administrator permission Settings → Payments is drawn on, because this decides which merchant account receives the money; a change of account is audited (masked, before and after) and emailed to the owner.", "operationId": "putApiPaymentGatewaysPayfastCredentials", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "string" }, "merchantKey": { "type": "string" }, "passphrase": { "type": "string" }, "sandbox": { "type": "boolean" }, "active": { "type": "boolean" }, "companyScoped": { "type": "boolean" } } }, "example": { "merchantId": "10000100", "merchantKey": "46f0cd694581a", "passphrase": "jt7NOE43FZPn", "sandbox": true, "active": true, "companyScoped": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPaymentGatewaysPayfastCredentialsResponse" }, "example": { "configured": true, "source": "referral", "merchantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "merchantKeyHint": "text", "hasPassphrase": false, "sandbox": true, "active": true, "companyScoped": false, "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Payments & gateways" ], "summary": "Remove stored credentials. Payment links already minted stop resolving a merchant.", "operationId": "deleteApiPaymentGatewaysPayfastCredentials", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "companyScoped", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payment-gateways/yoco/credentials": { "get": { "tags": [ "Payments & gateways" ], "summary": "The tenant's Yoco account. The secret key is write-only and comes back only as a masked hint. Also returns the exact webhook URL to register in the Yoco portal, and what is still missing before a payment could be reported. Read is gated on invoices:view.", "operationId": "getApiPaymentGatewaysYocoCredentials", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPaymentGatewaysYocoCredentialsResponse" }, "example": { "configured": false, "source": "referral", "secretKeyHint": "text", "hasWebhookSecret": false, "live": false, "active": true, "companyScoped": false, "setupBlocker": "text", "webhookUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Payments & gateways" ], "summary": "Store the tenant's Yoco secret key and webhook signing secret, encrypted with SecretBox. Gated on roles:edit, the administrator permission Settings → Payments is drawn on, because this decides which merchant account receives the money; a change of account is audited (masked, before and after) and emailed to the owner. Omitting webhookSecret leaves any stored one alone, because the two halves arrive separately: Yoco only reveals the signing secret once the webhook is registered, and registering it needs the URL this endpoint returns.", "operationId": "putApiPaymentGatewaysYocoCredentials", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secretKey": { "type": "string" }, "webhookSecret": { "type": "string" }, "active": { "type": "boolean" }, "companyScoped": { "type": "boolean" } } }, "example": { "secretKey": "sk_test_abcdefghij1234567890", "webhookSecret": "whsec_abcdefghij1234567890", "active": true, "companyScoped": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPaymentGatewaysYocoCredentialsResponse" }, "example": { "configured": true, "source": "referral", "secretKeyHint": "text", "hasWebhookSecret": false, "live": false, "active": true, "companyScoped": false, "setupBlocker": "text", "webhookUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Payments & gateways" ], "summary": "Remove the stored Yoco account. Payment links already minted stop resolving an account.", "operationId": "deleteApiPaymentGatewaysYocoCredentials", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "companyScoped", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/webhook-events": { "get": { "tags": [ "Payments & gateways" ], "summary": "The payments inbox — incoming gateway events with their match state, matched, review or unmatched.", "operationId": "getApiWebhookEvents", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWebhookEventsResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ts": "2026-09-01T09:15:00Z", "gateway": "payfast", "ref": "INV-0001", "amount": 10005.0, "currency": "ZAR", "matched": "text", "status": "sent", "note": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/webhook-events/{id}/match": { "post": { "tags": [ "Payments & gateways" ], "summary": "Match an unmatched payment to an invoice by hand.", "operationId": "postApiWebhookEventsByIdMatch", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceNumber": { "type": "string" } } }, "example": { "invoiceNumber": "INV-0001" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWebhookEventsResponseItem" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ts": "2026-09-01T09:15:00Z", "gateway": "payfast", "ref": "INV-0001", "amount": 10005.0, "currency": "ZAR", "matched": "text", "status": "sent", "note": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/lead-form/{token}": { "get": { "tags": [ "Customer portal" ], "summary": "A business's hosted enquiry form, for a business with no website form of its own: name, company, email or phone, and a message. Each rendered form carries its own nonce. With sent=1 it thanks the visitor. An unknown or rotated link is 404.", "operationId": "getLeadFormByToken", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sent", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" } ], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Customer portal" ], "summary": "A visitor sends the hosted enquiry form: one new, unassigned website lead on the form's company, answered with a 303 back to the thank-you page. The same form posted twice (its nonce) is one lead; a form with no email or phone is refused with 422 and writes nothing. Rate-limited per caller.", "operationId": "postLeadFormByToken", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } } }, "/api/crm/leads": { "get": { "tags": [ "Sales CRM" ], "summary": "Leads, paginated. The client reports \"50 of 312\" because a list that silently stops at fifty while looking complete is the failure paging was meant to fix.", "operationId": "getApiCrmLeads", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" }, { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "new" }, { "name": "ownerId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" }, "example": "referral" }, { "name": "search", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmLeadsResponse" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "companyName": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "source": "referral", "status": "new", "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "estimatedValue": 10005.0, "currency": "ZAR", "campaignId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "campaignName": "Karoo Fresh Holdings Ltd", "notes": "Budget deferred to the next financial year.", "convertedContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "convertedAt": "2026-09-01T09:15:00Z", "lostReason": "Budget deferred to the next financial year.", "activityCount": 3, "openTaskCount": 3, "lastActivityAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ], "total": 42, "page": 1, "limit": 50, "totalPages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Sales CRM" ], "summary": "Capture a lead.", "operationId": "postApiCrmLeads", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "name": { "type": "string" }, "companyName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "ownerUserId": { "type": "string" }, "estimatedValue": { "type": "number" }, "currency": { "type": "string" }, "campaignId": { "type": "string" }, "notes": { "type": "string" } } }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Sipho Dlamini", "companyName": "Dlamini Logistics", "email": "sipho@dlamini.example", "phone": "+27821234567", "source": "referral", "status": "new", "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "estimatedValue": 85000.0, "currency": "ZAR", "campaignId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmLeadsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCrmLeadsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/leads/{id}": { "get": { "tags": [ "Sales CRM" ], "summary": "One lead with its activities.", "operationId": "getApiCrmLeadsById", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmLeadsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCrmLeadsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Sales CRM" ], "summary": "Update a lead or move its status through new, contacted, qualified, unqualified.", "operationId": "putApiCrmLeadsById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "companyName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "ownerUserId": { "type": "string" }, "estimatedValue": { "type": "number" }, "currency": { "type": "string" }, "campaignId": { "type": "string" }, "notes": { "type": "string" }, "lostReason": { "type": "string" } } }, "example": { "name": "Karoo Fresh Holdings Ltd", "companyName": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "source": "referral", "status": "qualified", "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "estimatedValue": 92000.0, "currency": "ZAR", "campaignId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "lostReason": "Budget deferred to the next financial year." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmLeadsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCrmLeadsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "tags": [ "Sales CRM" ], "summary": "Apply an edit made against a copy of the lead, merged with anything changed since: fields nobody else changed are written, a field changed elsewhere to a different value answers 409 with both values and writes nothing, and a replayed edit id is answered as done.", "operationId": "patchApiCrmLeadsById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchApiContactsByIdRequest" }, "examples": { "default": { "$ref": "#/components/examples/PatchApiContactsByIdRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmLeadsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCrmLeadsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Sales CRM" ], "summary": "Delete a lead.", "operationId": "deleteApiCrmLeadsById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/leads/{id}/convert": { "post": { "tags": [ "Sales CRM" ], "summary": "Convert to a real contact, carrying the lead's activities across. Never duplicates a customer on the same email — the match runs through the same contactMatchKey the import uses.", "operationId": "postApiCrmLeadsByIdConvert", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactType": { "type": "string" }, "createOpportunity": { "type": "boolean" }, "opportunityName": { "type": "string" }, "opportunityValue": { "type": "number" }, "pipelineId": { "type": "string" }, "stageId": { "type": "string" }, "expectedCloseDate": { "type": "string", "format": "date" } } }, "example": { "contactType": "customer", "createOpportunity": true, "opportunityName": "Karoo Fresh Holdings Ltd", "opportunityValue": 10005.0, "pipelineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stageId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "expectedCloseDate": "2026-09-01" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "leadId": { "type": "string" }, "contactId": { "type": "string" }, "contactCreated": { "type": "boolean" }, "opportunityId": { "type": "string" }, "activitiesMoved": { "type": "integer" } } }, "example": { "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactCreated": true, "opportunityId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "activitiesMoved": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/leads/import": { "post": { "tags": [ "Sales CRM" ], "summary": "Import leads from CSV. Set preview to run the same code and return the counts without writing. Deliberately forgiving: the only rejection is a row with no name, and money goes through parseFlexibleAmount because a pasted \"R1 500,50\" is what a South African spreadsheet contains.", "operationId": "postApiCrmLeadsImport", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "preview", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "integer" }, "duplicates": { "type": "integer" }, "skipped": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object" } }, "detectedColumns": { "$ref": "#/components/schemas/GetApiPayrollSettingsResponseDesignLabels" }, "previewOnly": { "type": "boolean" } } }, "example": { "created": 1, "duplicates": 1, "skipped": 1, "errors": [], "detectedColumns": { "key": "text" }, "previewOnly": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/pipeline": { "get": { "tags": [ "Sales CRM" ], "summary": "The kanban board — every open deal by stage, with count, total and weighted total per column.", "operationId": "getApiCrmPipeline", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "ownerId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "pipelineId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "stage": { "$ref": "#/components/schemas/PostApiCrmStagesResponse" }, "count": { "type": "integer" }, "totalValue": { "type": "number" }, "weightedValue": { "type": "number" }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "leadId": { "type": "string" }, "stageId": { "type": "string" }, "stageName": { "type": "string" }, "stageIsWon": { "type": "boolean" }, "stageIsLost": { "type": "boolean" }, "ownerUserId": { "type": "string" }, "ownerName": { "type": "string" }, "value": { "type": "number" }, "currency": { "type": "string" }, "probability": { "type": "number" }, "weightedValue": { "type": "number" }, "expectedCloseDate": { "type": "string", "format": "date" }, "source": { "type": "string" }, "status": { "type": "string" }, "lostReason": { "type": "string" }, "closedAt": { "type": "string" }, "campaignId": { "type": "string" }, "campaignName": { "type": "string" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponseLinesItem" } }, "lineCount": { "type": "integer" }, "totals": { "type": "object", "properties": { "currency": { "type": "string" }, "subtotal": { "type": "number" }, "discountTotal": { "type": "number" }, "vatTotal": { "type": "number" }, "netValue": { "type": "number" }, "grossValue": { "type": "number" }, "lineCount": { "type": "integer" }, "margin": { "type": "null" } } }, "decision": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponseDecision" }, "ageDays": { "type": "integer" }, "activityCount": { "type": "integer" }, "openTaskCount": { "type": "integer" }, "nextActivityDue": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } } } }, "openCount": { "type": "integer" }, "openValue": { "type": "number" }, "weightedForecast": { "type": "number" }, "overdueCount": { "type": "integer" } } }, "example": { "currency": "ZAR", "columns": [ { "stage": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "sortOrder": 1, "defaultProbability": 15.0, "isWon": false, "isLost": false, "isActive": true }, "count": 3, "totalValue": 10005.0, "weightedValue": 10005.0, "opportunities": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stageId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stageName": "Karoo Fresh Holdings Ltd", "stageIsWon": false, "stageIsLost": false, "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "value": 10005.0, "currency": "ZAR", "probability": 15.0, "weightedValue": 10005.0, "expectedCloseDate": "2026-09-01", "source": "referral", "status": "sent", "lostReason": "Budget deferred to the next financial year.", "closedAt": "2026-09-01T09:15:00Z", "campaignId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "campaignName": "Karoo Fresh Holdings Ltd", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "kind": "PRODUCT", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productCode": "CT-001", "quantity": 3.0, "unitPrice": 2900.0, "unitCost": 2900.0, "discountRate": 0.0, "discountFixed": 0.0, "discountType": "PERCENT", "vatRate": 15.0, "vatInclusive": false, "notes": "Budget deferred to the next financial year.", "lineSubtotal": 8700.0, "discountAmount": 0.0, "vatAmount": 1305.0, "lineTotal": 10005.0 } ], "lineCount": 3, "totals": { "currency": "ZAR", "subtotal": 8700.0, "discountTotal": 0.0, "vatTotal": 1305.0, "netValue": 8700.0, "grossValue": 10005.0, "lineCount": 3, "margin": null }, "decision": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "status": "sent", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena", "declineReason": "Budget deferred to the next financial year.", "awaitingDecision": false }, "ageDays": 30, "activityCount": 3, "openTaskCount": 3, "nextActivityDue": "text", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } ], "openCount": 3, "openValue": 10005.0, "weightedForecast": 1.0, "overdueCount": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/opportunities": { "get": { "tags": [ "Sales CRM" ], "summary": "Deals as a table, soonest close date first. The answer is always one page of { items, total, page, limit, totalPages } (50 a page unless limit asks for another size, at most 200), the same paginated shape GET /api/crm/leads answers. Since API v2 this holds with neither page nor limit too; v1 answered every deal as one array. Every filter and the search run over every deal before a page is cut, and total counts them; pipelineId keeps one pipeline's deals. The board (GET /api/crm/pipeline) is the whole open pipeline.", "operationId": "getApiCrmOpportunities", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" }, { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "pipelineId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "stageId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "open" }, { "name": "ownerId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "contactId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "search", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponse" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stageId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stageName": "Karoo Fresh Holdings Ltd", "stageIsWon": false, "stageIsLost": false, "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "value": 10005.0, "currency": "ZAR", "probability": 15.0, "weightedValue": 10005.0, "expectedCloseDate": "2026-09-01", "source": "referral", "status": "open", "lostReason": "Budget deferred to the next financial year.", "closedAt": "2026-09-01T09:15:00Z", "campaignId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "campaignName": "Karoo Fresh Holdings Ltd", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "kind": "PRODUCT", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productCode": "CT-001", "quantity": 3.0, "unitPrice": 2900.0, "unitCost": 2900.0, "discountRate": 0.0, "discountFixed": 0.0, "discountType": "PERCENT", "vatRate": 15.0, "vatInclusive": false, "notes": "Budget deferred to the next financial year.", "lineSubtotal": 8700.0, "discountAmount": 0.0, "vatAmount": 1305.0, "lineTotal": 10005.0 } ], "lineCount": 3, "totals": { "currency": "ZAR", "subtotal": 8700.0, "discountTotal": 0.0, "vatTotal": 1305.0, "netValue": 8700.0, "grossValue": 10005.0, "lineCount": 3, "margin": { "revenue": 1.0, "cost": 10005.0, "profit": 1.0, "marginPct": 1.0, "costKnownForAllLines": true } }, "decision": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "status": "sent", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena", "declineReason": "Budget deferred to the next financial year.", "awaitingDecision": false }, "ageDays": 30, "activityCount": 3, "openTaskCount": 3, "nextActivityDue": "text", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ], "total": 42, "page": 1, "limit": 50, "totalPages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Sales CRM" ], "summary": "Create a deal. A deal with no lines keeps its typed value, which is the normal early state rather than a fallback.", "operationId": "postApiCrmOpportunities", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pipelineId": { "type": "string" }, "name": { "type": "string" }, "contactId": { "type": "string" }, "leadId": { "type": "string" }, "stageId": { "type": "string" }, "ownerUserId": { "type": "string" }, "value": { "type": "number" }, "currency": { "type": "string" }, "probability": { "type": "number" }, "expectedCloseDate": { "type": "string", "format": "date" }, "source": { "type": "string" }, "campaignId": { "type": "string" }, "notes": { "type": "string" } } }, "example": { "pipelineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Warehouse expansion", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stageId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "value": 26700.0, "currency": "ZAR", "probability": 15.0, "expectedCloseDate": "2026-10-31", "source": "referral", "campaignId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCrmOpportunitiesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/opportunities/{id}": { "get": { "tags": [ "Sales CRM" ], "summary": "One deal, with its line count so a single-line deal is told apart from a priced one at the call site.", "operationId": "getApiCrmOpportunitiesById", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCrmOpportunitiesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Sales CRM" ], "summary": "Update a deal. Once it has lines, value is DERIVED — recomputeOpportunityValue is its only writer.", "operationId": "putApiCrmOpportunitiesById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "contactId": { "type": "string" }, "ownerUserId": { "type": "string" }, "value": { "type": "number" }, "currency": { "type": "string" }, "probability": { "type": "number" }, "expectedCloseDate": { "type": "string", "format": "date" }, "source": { "type": "string" }, "campaignId": { "type": "string" }, "notes": { "type": "string" } } }, "example": { "name": "Warehouse expansion phase 2", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "value": 10005.0, "currency": "ZAR", "probability": 15.0, "expectedCloseDate": "2026-11-30", "source": "referral", "campaignId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCrmOpportunitiesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Sales CRM" ], "summary": "Delete a deal and its lines.", "operationId": "deleteApiCrmOpportunitiesById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/opportunities/{id}/stage": { "post": { "tags": [ "Sales CRM" ], "summary": "Move a deal. Every move writes a history row, which is where cycle time comes from.", "operationId": "postApiCrmOpportunitiesByIdStage", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stageId": { "type": "string" }, "probability": { "type": "number" }, "lostReason": { "type": "string" }, "note": { "type": "string" } } }, "example": { "stageId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "probability": 15.0, "lostReason": "Budget deferred to the next financial year.", "note": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCrmOpportunitiesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/opportunities/{id}/history": { "get": { "tags": [ "Sales CRM" ], "summary": "Every stage this deal has been through, and when.", "operationId": "getApiCrmOpportunitiesByIdHistory", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fromStageId": { "type": "string" }, "fromStageName": { "type": "string" }, "toStageId": { "type": "string" }, "toStageName": { "type": "string" }, "fromProbability": { "type": "number" }, "toProbability": { "type": "number" }, "daysInPreviousStage": { "type": "integer" }, "changedByUserId": { "type": "string" }, "changedByName": { "type": "string" }, "note": { "type": "string" }, "changedAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromStageId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromStageName": "Karoo Fresh Holdings Ltd", "toStageId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toStageName": "Karoo Fresh Holdings Ltd", "fromProbability": 15.0, "toProbability": 15.0, "daysInPreviousStage": 30, "changedByUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "changedByName": "Karoo Fresh Holdings Ltd", "note": "Budget deferred to the next financial year.", "changedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/opportunities/{id}/lines": { "get": { "tags": [ "Sales CRM" ], "summary": "The deal's lines. They mirror invoice_lines field for field, so a line becomes an InvoiceLineRequest with no conversion step.", "operationId": "getApiCrmOpportunitiesByIdLines", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponseLinesItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "kind": "PRODUCT", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productCode": "CT-001", "quantity": 3.0, "unitPrice": 2900.0, "unitCost": 2900.0, "discountRate": 0.0, "discountFixed": 0.0, "discountType": "PERCENT", "vatRate": 15.0, "vatInclusive": false, "notes": "Budget deferred to the next financial year.", "lineSubtotal": 8700.0, "discountAmount": 0.0, "vatAmount": 1305.0, "lineTotal": 10005.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Sales CRM" ], "summary": "Replace the deal's lines and recompute its value in the same transaction. unit_cost is the one column invoice_lines does not have — snapshotted at pricing, nullable rather than zero, and it is what lets the board show margin on a deal that has not been invoiced.", "operationId": "putApiCrmOpportunitiesByIdLines", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "unitCost": { "type": "number" }, "vatRate": { "type": "number" } } } }, "example": [ { "description": "Steel frame", "quantity": 40.0, "unitPrice": 1850.0, "unitCost": 1240.0, "vatRate": 15.0 } ] } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponseTotals" }, "example": { "currency": "ZAR", "subtotal": 8700.0, "discountTotal": 0.0, "vatTotal": 1305.0, "netValue": 8700.0, "grossValue": 10005.0, "lineCount": 3, "margin": { "revenue": 1.0, "cost": 10005.0, "profit": 1.0, "marginPct": 1.0, "costKnownForAllLines": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/opportunities/{id}/quote": { "post": { "tags": [ "Sales CRM" ], "summary": "Raise a real quote through the invoicing engine from the deal's own lines, and store the link both ways.", "operationId": "postApiCrmOpportunitiesByIdQuote", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "invoice" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issueDate": { "type": "string", "format": "date" }, "validUntil": { "type": "string", "format": "date" } } }, "example": { "issueDate": "2026-08-22", "validUntil": "2026-09-22" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "documentType": { "type": "string" }, "lineCount": { "type": "integer" }, "total": { "type": "number" }, "currency": { "type": "string" } } }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "documentType": "quote", "lineCount": 3, "total": 10005.0, "currency": "ZAR" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/lead-form": { "get": { "tags": [ "Sales CRM" ], "summary": "The company's hosted enquiry form link (/lead-form/{token}), minted on first ask. A visitor's enquiry there becomes a new, unassigned website lead on this company. Null when the deployment has no public address.", "operationId": "getApiCrmLeadForm", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiCrmLeadFormResponse" }, "example": { "url": "https://app.ledgrsa.com/pay/3f1a7c92" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/lead-form/rotate": { "post": { "tags": [ "Sales CRM" ], "summary": "A new hosted enquiry form link; the old one stops working at once, for the page and its post.", "operationId": "postApiCrmLeadFormRotate", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiCrmLeadFormResponse" }, "example": { "url": "https://app.ledgrsa.com/pay/3f1a7c92" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/emails": { "post": { "tags": [ "Sales CRM" ], "summary": "Send an email from one lead or one deal, from the business with Reply-To the salesperson, and record it once as an email activity on its timeline (and the contact's history). The address is the lead's or the deal contact's unless 'to' names one. A retry with the same clientId answers 200 with the activity already made and sends nothing; the activity's outcome says whether the mail service accepted it.", "operationId": "postApiCrmEmails", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmEmailsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "activityType": "call", "subject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached.", "dueDate": "2026-09-01", "completedAt": "2026-09-01T09:15:00Z", "isOverdue": false, "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leadName": "Karoo Fresh Holdings Ltd", "opportunityId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "opportunityName": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "outcome": "text", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/bcc-address": { "get": { "tags": [ "Sales CRM" ], "summary": "The company's BCC-to-CRM address: an email a salesperson sends from their own mail with this address in BCC lands on the lead (else the contact's open deal) it was written to, once per Message-ID. Null when the deployment receives no email.", "operationId": "getApiCrmBccAddress", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiCrmBccAddressResponse" }, "example": { "address": "12 Long Street, Cape Town, 8001" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/pipelines": { "get": { "tags": [ "Sales CRM" ], "summary": "The tenant's sales pipelines, the default first, each with how many open deals stand in its stages.", "operationId": "getApiCrmPipelines", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmPipelinesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "sortOrder": 1, "isDefault": false, "openDeals": 1 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Sales CRM" ], "summary": "Add a sales pipeline; it gets the standard stages (Qualification to Closed won and Closed lost). A name already in use is refused with 409.", "operationId": "postApiCrmPipelines", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmPipelinesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "sortOrder": 1, "isDefault": false, "openDeals": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/pipelines/{id}": { "put": { "tags": [ "Sales CRM" ], "summary": "Rename a pipeline.", "operationId": "putApiCrmPipelinesById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmPipelinesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "sortOrder": 1, "isDefault": false, "openDeals": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Sales CRM" ], "summary": "Delete a pipeline and its stages. Refused with 409 for the default pipeline, and for one that still holds deals — move them first.", "operationId": "deleteApiCrmPipelinesById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/stages": { "get": { "tags": [ "Sales CRM" ], "summary": "The tenant's pipeline stages and their default probabilities.", "operationId": "getApiCrmStages", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmStagesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "sortOrder": 1, "defaultProbability": 15.0, "isWon": false, "isLost": false, "isActive": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Sales CRM" ], "summary": "Add a stage.", "operationId": "postApiCrmStages", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pipelineId": { "type": "string" }, "name": { "type": "string" }, "sortOrder": { "type": "integer" }, "defaultProbability": { "type": "integer" }, "isWon": { "type": "boolean" }, "isLost": { "type": "boolean" }, "isActive": { "type": "boolean" } } }, "example": { "pipelineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Site survey", "sortOrder": 2, "defaultProbability": 35, "isWon": true, "isLost": true, "isActive": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmStagesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "sortOrder": 1, "defaultProbability": 15.0, "isWon": false, "isLost": false, "isActive": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/stages/{id}": { "put": { "tags": [ "Sales CRM" ], "summary": "Rename, reorder or reprobability a stage.", "operationId": "putApiCrmStagesById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "sortOrder": { "type": "integer" }, "defaultProbability": { "type": "number" }, "isWon": { "type": "boolean" }, "isLost": { "type": "boolean" }, "isActive": { "type": "boolean" } } }, "example": { "name": "Karoo Fresh Holdings Ltd", "sortOrder": 1, "defaultProbability": 15.0, "isWon": true, "isLost": true, "isActive": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmStagesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "sortOrder": 1, "defaultProbability": 15.0, "isWon": false, "isLost": false, "isActive": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Sales CRM" ], "summary": "Remove a stage. Refused while deals sit in it.", "operationId": "deleteApiCrmStagesById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/activities": { "get": { "tags": [ "Sales CRM" ], "summary": "Calls, meetings, emails, notes and tasks, paginated. Linked polymorphically to a lead, a deal or a contact.", "operationId": "getApiCrmActivities", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" }, { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "ownerId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "me" }, { "name": "type", "in": "query", "required": false, "description": "Restrict to one type. Matched case-insensitively; an unrecognised value is refused.", "schema": { "type": "string" }, "example": "call" }, { "name": "contactId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "opportunityId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "leadId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "open", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" }, { "name": "overdue", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmEmailsResponse" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "activityType": "call", "subject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached.", "dueDate": "2026-09-01", "completedAt": "2026-09-01T09:15:00Z", "isOverdue": false, "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leadName": "Karoo Fresh Holdings Ltd", "opportunityId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "opportunityName": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "outcome": "text", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ], "total": 42, "page": 1, "limit": 50, "totalPages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Sales CRM" ], "summary": "Log an activity or set a task. Logging one updates the contact's last_contacted_at, which is what makes \"nobody has called these fifteen customers in four months\" answerable.", "operationId": "postApiCrmActivities", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "activityType": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "completed": { "type": "boolean" }, "ownerUserId": { "type": "string" }, "leadId": { "type": "string" }, "opportunityId": { "type": "string" }, "contactId": { "type": "string" }, "outcome": { "type": "string" } } }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "activityType": "call", "subject": "Follow up on the frame quote", "body": "Your invoice INV-0001 is attached.", "dueDate": "2026-08-28", "completed": false, "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "opportunityId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "outcome": "Interested — sending a quote on Friday" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "activityType": { "type": "string" }, "subject": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "completedAt": { "type": "string" }, "isOverdue": { "type": "boolean" }, "ownerUserId": { "type": "string" }, "ownerName": { "type": "string" }, "leadId": { "type": "string" }, "leadName": { "type": "string" }, "opportunityId": { "type": "string" }, "opportunityName": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "outcome": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "body": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "activityType": "standard", "subject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "dueDate": "2026-09-01", "completedAt": "2026-09-01T09:15:00Z", "isOverdue": false, "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leadName": "Karoo Fresh Holdings Ltd", "opportunityId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "opportunityName": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "outcome": "text", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "body": "Your invoice INV-0001 is attached." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/activities/{id}": { "put": { "tags": [ "Sales CRM" ], "summary": "Change an activity.", "operationId": "putApiCrmActivitiesById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "activityType": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "ownerUserId": { "type": "string" }, "outcome": { "type": "string" } } }, "example": { "activityType": "standard", "subject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached.", "dueDate": "2026-08-29", "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "outcome": "Interested — sending a quote on Friday" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmEmailsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PutApiCrmActivitiesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Sales CRM" ], "summary": "Delete an activity.", "operationId": "deleteApiCrmActivitiesById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/activities/{id}/complete": { "post": { "tags": [ "Sales CRM" ], "summary": "Mark a task done.", "operationId": "postApiCrmActivitiesByIdComplete", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmEmailsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PutApiCrmActivitiesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/follow-ups": { "get": { "tags": [ "Sales CRM" ], "summary": "My open tasks, oldest due first — the read the crm-tasks digest chases. No \"upcoming this week\": a digest listing work that is not yet due trains people to ignore it.", "operationId": "getApiCrmFollowUps", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "ownerId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "me" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "contactId": { "type": "string" }, "contactName": { "type": "string" }, "lifecycleStage": { "type": "string" }, "nextFollowUpDate": { "type": "string", "format": "date" }, "lastContactedAt": { "type": "string" }, "ownerUserId": { "type": "string" }, "ownerName": { "type": "string" }, "bucket": { "type": "string" }, "daysOverdue": { "type": "integer" }, "daysSinceContact": { "type": "integer" } } } }, "example": [ { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "lifecycleStage": "text", "nextFollowUpDate": "2026-09-01", "lastContactedAt": "2026-09-01T09:15:00Z", "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "bucket": "text", "daysOverdue": 30, "daysSinceContact": 30 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/owners": { "get": { "tags": [ "Sales CRM" ], "summary": "Who can own a lead, a deal or a task.", "operationId": "getApiCrmOwners", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" } } } }, "example": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "role": "Accountant" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/performance": { "get": { "tags": [ "Sales CRM" ], "summary": "Pipeline by stage, weighted forecast, win rate, average sales cycle, and per-owner and per-source breakdowns.", "operationId": "getApiCrmPerformance", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "openCount": { "type": "integer" }, "openPipeline": { "type": "number" }, "weightedForecast": { "type": "number" }, "overdueCount": { "type": "integer" }, "wonCount": { "type": "integer" }, "wonValue": { "type": "number" }, "lostCount": { "type": "integer" }, "lostValue": { "type": "number" }, "winRatePct": { "type": "number" }, "avgSalesCycleDays": { "type": "number" }, "leadCount": { "type": "integer" }, "newLeadCount": { "type": "integer" }, "convertedLeadCount": { "type": "integer" }, "leadConversionRatePct": { "type": "number" }, "openLeadCount": { "type": "integer" }, "openLeadValue": { "type": "number" }, "activityCount": { "type": "integer" }, "openTaskCount": { "type": "integer" }, "overdueTaskCount": { "type": "integer" }, "byStage": { "type": "array", "items": { "type": "object", "properties": { "stageId": { "type": "string" }, "stageName": { "type": "string" }, "count": { "type": "integer" }, "totalValue": { "type": "number" }, "weightedValue": { "type": "number" } } } }, "byOwner": { "type": "array", "items": { "type": "object", "properties": { "ownerUserId": { "type": "string" }, "ownerName": { "type": "string" }, "openCount": { "type": "integer" }, "openValue": { "type": "number" }, "weightedValue": { "type": "number" }, "wonCount": { "type": "integer" }, "wonValue": { "type": "number" }, "lostCount": { "type": "integer" }, "winRatePct": { "type": "number" }, "avgCycleDays": { "type": "number" }, "activityCount": { "type": "integer" } } } }, "bySource": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "leadCount": { "type": "integer" }, "opportunityCount": { "type": "integer" }, "wonCount": { "type": "integer" }, "wonValue": { "type": "number" }, "weightedValue": { "type": "number" } } } }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmTargetsResponse" } } } }, "example": { "currency": "ZAR", "openCount": 3, "openPipeline": 1.0, "weightedForecast": 1.0, "overdueCount": 3, "wonCount": 3, "wonValue": 10005.0, "lostCount": 3, "lostValue": 10005.0, "winRatePct": 1.0, "avgSalesCycleDays": 1.0, "leadCount": 3, "newLeadCount": 3, "convertedLeadCount": 3, "leadConversionRatePct": 1.0, "openLeadCount": 3, "openLeadValue": 10005.0, "activityCount": 3, "openTaskCount": 3, "overdueTaskCount": 3, "byStage": [ { "stageId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stageName": "Karoo Fresh Holdings Ltd", "count": 3, "totalValue": 10005.0, "weightedValue": 10005.0 } ], "byOwner": [ { "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "openCount": 3, "openValue": 10005.0, "weightedValue": 10005.0, "wonCount": 3, "wonValue": 10005.0, "lostCount": 3, "winRatePct": 1.0, "avgCycleDays": 1.0, "activityCount": 3 } ], "bySource": [ { "source": "referral", "leadCount": 3, "opportunityCount": 3, "wonCount": 3, "wonValue": 10005.0, "weightedValue": 10005.0 } ], "targets": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "targetValue": 10005.0, "currency": "ZAR", "notes": "Budget deferred to the next financial year.", "actualValue": 10005.0, "attainmentPct": 1.0, "remaining": 1.0, "weightedForecast": 1.0, "isCurrent": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/targets": { "get": { "tags": [ "Sales CRM" ], "summary": "Sales targets by period. owner_user_id null means the team's number. Attainment is NOT capped at 100, and no target renders as \"no target set\" rather than 0%.", "operationId": "getApiCrmTargets", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmTargetsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "targetValue": 10005.0, "currency": "ZAR", "notes": "Budget deferred to the next financial year.", "actualValue": 10005.0, "attainmentPct": 1.0, "remaining": 1.0, "weightedForecast": 1.0, "isCurrent": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Sales CRM" ], "summary": "Set a target. Measured against won deal value net of VAT, attributed by closed_at — the period it was won in, not the one somebody hoped.", "operationId": "postApiCrmTargets", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmTargetsRequest" }, "example": { "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "targetValue": 250000.0, "currency": "ZAR", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmTargetsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCrmTargetsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/targets/{id}": { "put": { "tags": [ "Sales CRM" ], "summary": "Change a target.", "operationId": "putApiCrmTargetsById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmTargetsRequest" }, "example": { "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "targetValue": 300000.0, "currency": "ZAR", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmTargetsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCrmTargetsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Sales CRM" ], "summary": "Remove a target.", "operationId": "deleteApiCrmTargetsById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/campaigns": { "get": { "tags": [ "Sales CRM" ], "summary": "Campaigns with channel, window, budget against spend, and attributed leads, deals and won revenue.", "operationId": "getApiCrmCampaigns", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmCampaignsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "channel": "email", "startDate": "2026-09-01", "endDate": "2026-09-30", "budget": 1.0, "spend": 1.0, "currency": "ZAR", "status": "sent", "targetAudience": "text", "notes": "Budget deferred to the next financial year.", "leadCount": 3, "convertedLeadCount": 3, "opportunityCount": 3, "wonCount": 3, "wonRevenue": 1.0, "weightedPipeline": 1.0, "roiPct": 1.0, "costPerLead": 10005.0, "conversionRatePct": 1.0, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Sales CRM" ], "summary": "Create a campaign. Attribution is by the lead's source, so it is only as honest as the capture.", "operationId": "postApiCrmCampaigns", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmCampaignsRequest" }, "example": { "name": "Spring trade show", "channel": "event", "startDate": "2026-09-01", "endDate": "2026-09-30", "budget": 40000.0, "spend": 1.0, "currency": "ZAR", "status": "sent", "targetAudience": "Existing customers in Gauteng", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmCampaignsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCrmCampaignsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/campaigns/{id}": { "put": { "tags": [ "Sales CRM" ], "summary": "Update a campaign or record spend against it.", "operationId": "putApiCrmCampaignsById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmCampaignsRequest" }, "example": { "name": "Karoo Fresh Holdings Ltd", "channel": "email", "startDate": "2026-09-01", "endDate": "2026-09-30", "budget": 1.0, "spend": 38200.0, "currency": "ZAR", "status": "sent", "targetAudience": "Existing customers in Gauteng", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmCampaignsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCrmCampaignsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Sales CRM" ], "summary": "Delete a campaign.", "operationId": "deleteApiCrmCampaignsById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/attachments": { "get": { "tags": [ "Sales CRM" ], "summary": "Files linked to a deal, a lead or a contact. A link table rather than a column, because a deal has several and a single column means the second upload silently replaces the first.", "operationId": "getApiCrmAttachments", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opportunityId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "leadId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "contactId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmAttachmentsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "contentType": "application/pdf", "sizeBytes": 1, "url": "https://app.ledgrsa.com/pay/3f1a7c92", "createdAt": "2026-09-01T09:15:00Z", "createdByName": "Thandi Mokoena" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Sales CRM" ], "summary": "Link an attachment to a deal, a lead or a contact.", "operationId": "postApiCrmAttachments", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "attachmentId": { "type": "string" }, "label": { "type": "string" }, "leadId": { "type": "string" }, "opportunityId": { "type": "string" }, "contactId": { "type": "string" } } }, "example": { "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Signed acceptance", "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "opportunityId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCrmAttachmentsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "contentType": "application/pdf", "sizeBytes": 1, "url": "https://app.ledgrsa.com/pay/3f1a7c92", "createdAt": "2026-09-01T09:15:00Z", "createdByName": "Thandi Mokoena" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/attachments/upload": { "post": { "tags": [ "Sales CRM" ], "summary": "Store a file and return its id. Raw bytes with the content type in the header, never base64 — a picker hands the client a ByteArray on every target and base64 inflates a 4MB drawing by a third. The server decides the stored content type from a closed list, never the one the client claims. The id then goes to POST /api/crm/attachments, which is what decides where it may be attached.", "operationId": "postApiCrmAttachmentsUpload", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachmentId": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" } } }, "example": { "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contentType": "application/pdf", "sizeBytes": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/attachments/{id}": { "delete": { "tags": [ "Sales CRM" ], "summary": "Unlink. Removes the LINK, not the file — the same attachment may be referenced elsewhere, and a CRM screen is not where somebody should be able to destroy a receipt.", "operationId": "deleteApiCrmAttachmentsById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "unlinked" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/contacts/{id}/summary": { "get": { "tags": [ "Sales CRM" ], "summary": "The CRM panel inside the contact detail view — open deals, recent activities and lifecycle stage. One contact record, two views onto it.", "operationId": "getApiCrmContactsByIdSummary", "description": "Requires the `crm:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "lifecycleStage": { "type": "string" }, "industry": { "type": "string" }, "website": { "type": "string" }, "nextFollowUpDate": { "type": "string", "format": "date" }, "lastContactedAt": { "type": "string" }, "ownerUserId": { "type": "string" }, "ownerName": { "type": "string" }, "openOpportunityCount": { "type": "integer" }, "openOpportunityValue": { "type": "number" }, "weightedValue": { "type": "number" }, "wonCount": { "type": "integer" }, "wonValue": { "type": "number" }, "openTaskCount": { "type": "integer" }, "overdueTaskCount": { "type": "integer" }, "isStale": { "type": "boolean" }, "opportunities": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponse" } } } }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lifecycleStage": "text", "industry": "text", "website": "https://app.ledgrsa.com/pay/3f1a7c92", "nextFollowUpDate": "2026-09-01", "lastContactedAt": "2026-09-01T09:15:00Z", "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "openOpportunityCount": 3, "openOpportunityValue": 10005.0, "weightedValue": 10005.0, "wonCount": 3, "wonValue": 10005.0, "openTaskCount": 3, "overdueTaskCount": 3, "isStale": false, "opportunities": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stageId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stageName": "Karoo Fresh Holdings Ltd", "stageIsWon": false, "stageIsLost": false, "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownerName": "Thandi Mokoena", "value": 10005.0, "currency": "ZAR", "probability": 15.0, "weightedValue": 10005.0, "expectedCloseDate": "2026-09-01", "source": "referral", "status": "sent", "lostReason": "Budget deferred to the next financial year.", "closedAt": "2026-09-01T09:15:00Z", "campaignId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "campaignName": "Karoo Fresh Holdings Ltd", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "kind": "PRODUCT", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productCode": "CT-001", "quantity": 3.0, "unitPrice": 2900.0, "unitCost": 2900.0, "discountRate": 0.0, "discountFixed": 0.0, "discountType": "PERCENT", "vatRate": 15.0, "vatInclusive": false, "notes": "Budget deferred to the next financial year.", "lineSubtotal": 8700.0, "discountAmount": 0.0, "vatAmount": 1305.0, "lineTotal": 10005.0 } ], "lineCount": 3, "totals": { "currency": "ZAR", "subtotal": 8700.0, "discountTotal": 0.0, "vatTotal": 1305.0, "netValue": 8700.0, "grossValue": 10005.0, "lineCount": 3, "margin": { "revenue": 1.0, "cost": 10005.0, "profit": 1.0, "marginPct": 1.0, "costKnownForAllLines": true } }, "decision": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "status": "sent", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena", "declineReason": "Budget deferred to the next financial year.", "awaitingDecision": false }, "ageDays": 30, "activityCount": 3, "openTaskCount": 3, "nextActivityDue": "text", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/crm/contacts/{id}": { "put": { "tags": [ "Sales CRM" ], "summary": "Set the CRM enrichment — lifecycle stage, industry, website and next follow-up.", "operationId": "putApiCrmContactsById", "description": "Requires the `crm:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "crm:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lifecycleStage": { "type": "string" }, "industry": { "type": "string" }, "website": { "type": "string" } } }, "example": { "lifecycleStage": "customer", "industry": "Logistics", "website": "https://dlamini.example" } } } }, "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/customer-api/v1/session": { "get": { "tags": [ "Customer ordering portal API" ], "summary": "Who the token belongs to, which business they are buying from, and what is waiting.", "operationId": "getCustomerApiV1Session", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerName": { "type": "string" }, "sellerName": { "type": "string" }, "productCount": { "type": "integer" }, "quotesAwaitingResponse": { "type": "integer" }, "quotesReadyToReview": { "type": "integer" }, "openInvoices": { "type": "integer" }, "amountOutstanding": { "type": "number" }, "currency": { "type": "string" }, "accessExpiresAt": { "type": "string" } } }, "example": { "customerName": "Acme Trading", "sellerName": "Dlamini Supplies", "productCount": 240, "quotesAwaitingResponse": 1, "quotesReadyToReview": 2, "openInvoices": 3, "amountOutstanding": 18450.0, "currency": "ZAR", "accessExpiresAt": "2027-09-11T08:14:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/customer-api/v1/products": { "get": { "tags": [ "Customer ordering portal API" ], "summary": "The price book: products flagged is_sellable, at the standard sell price. Carries no cost price and no stock quantity — only an in-stock indicator, and null on an item that is not stock-tracked.", "operationId": "getCustomerApiV1Products", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "unit": { "type": "string" }, "unitPrice": { "type": "number" }, "vatRate": { "type": "number" }, "inStock": { "type": "boolean" }, "qtyPrecision": { "type": "integer" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "BOLT-M8-50", "name": "M8 x 50mm hex bolt", "category": "fasteners", "unit": "each", "unitPrice": 4.5, "vatRate": 15.0, "inStock": true, "qtyPrecision": 0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/customer-api/v1/basket": { "post": { "tags": [ "Customer ordering portal API" ], "summary": "Submit a basket. Produces a DRAFT quote priced from the seller's own price book, in its own currency and at the VAT the seller actually charges — it commits the business to nothing until a person reviews and sends it. Send a clientReference to make a retry safe: the same value answers the quote the first request made.", "operationId": "postCustomerApiV1Basket", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "quantity": { "type": "integer" } } } }, "reference": { "type": "string" }, "note": { "type": "string" }, "contactName": { "type": "string" }, "clientReference": { "type": "string" } } }, "example": { "lines": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 20 } ], "reference": "PO-4471", "note": "Needed before Friday.", "contactName": "Thandi Mokoena", "clientReference": "po-4471-try-1" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" }, "quote": { "type": "object", "properties": { "number": { "type": "string" }, "status": { "type": "string" }, "total": { "type": "number" }, "currency": { "type": "string" }, "submittedByCustomer": { "type": "boolean" }, "awaitingSeller": { "type": "boolean" } } } } }, "example": { "ok": true, "message": "Thank you — Dlamini Supplies has your request and will come back to you with a quote.", "quote": { "number": "QTE-2026-118", "status": "draft", "total": 103.5, "currency": "ZAR", "submittedByCustomer": false, "awaitingSeller": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/customer-api/v1/quotes": { "get": { "tags": [ "Customer ordering portal API" ], "summary": "Their quotes — the ones they submitted and the ones the seller has sent back. A draft the SELLER is still working on is deliberately not listed.", "operationId": "getCustomerApiV1Quotes", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "total": { "type": "number" }, "currency": { "type": "string" }, "submittedByCustomer": { "type": "boolean" }, "awaitingSeller": { "type": "boolean" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "QTE-2026-118", "status": "draft", "issueDate": "2026-09-11", "total": 103.5, "currency": "ZAR", "submittedByCustomer": false, "awaitingSeller": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/customer-api/v1/quotes/{id}": { "get": { "tags": [ "Customer ordering portal API" ], "summary": "One quote with its lines. 404 when it is not on this customer's account.", "operationId": "getCustomerApiV1QuotesById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string" }, "subtotal": { "type": "number" }, "vatTotal": { "type": "number" }, "total": { "type": "number" }, "currency": { "type": "string" }, "submittedByCustomer": { "type": "boolean" }, "awaitingSeller": { "type": "boolean" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "vatRate": { "type": "number" }, "lineTotal": { "type": "number" } } } } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "QTE-2026-118", "status": "draft", "subtotal": 90.0, "vatTotal": 13.5, "total": 103.5, "currency": "ZAR", "submittedByCustomer": false, "awaitingSeller": false, "lines": [ { "description": "M8 x 50mm hex bolt", "sku": "BOLT-M8-50", "quantity": 20.0, "unitPrice": 4.5, "vatRate": 15.0, "lineTotal": 103.5 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses": { "get": { "tags": [ "Expenses & claims" ], "summary": "Expense entries, newest first. Filtered in SQL: status (comma-separated, any case), category (uncategorised matches none set), q (supplier, description or note), from/to (the expense date, inclusive) and jobCardId (an id, or none). With no limit it is the whole list; limit (at most 500) and offset page it, and GET /api/expenses/count gives the total for the same filters.", "operationId": "getApiExpenses", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "submitted,approved" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "example": "fuel" }, { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "engen" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "jobCardId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" }, { "name": "offset", "in": "query", "required": false, "description": "How many rows to skip. Use with `limit` to page. A paged response reports `total`, which is the number of rows matching the filter rather than the number returned.", "schema": { "type": "integer" }, "example": "0" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiExpensesByIdResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "vendor": "Karoo Fresh Holdings Ltd", "supplierVatNumber": "4123456789", "category": "Office supplies", "amount": 10005.0, "vatAmount": 1305.0, "vatRate": 15.0, "currency": "ZAR", "status": "sent", "receiptUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "notes": "Budget deferred to the next financial year.", "rejectionReason": "Budget deferred to the next financial year.", "createdBy": "Thandi Mokoena", "createdByName": "Thandi Mokoena", "approvedBy": "Thandi Mokoena", "approvedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectName": "Karoo Fresh Holdings Ltd", "rechargeable": false, "rechargeInvoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Expenses & claims" ], "summary": "Capture an expense. Accepts a client-minted id, which is what makes offline replay idempotent — the id becomes the row's primary key. A purchase of goods received by hand can name productId and productQty: it is booked to Purchases and clears those goods from 2115 Goods Received Not Invoiced, and a price difference follows the stock.", "operationId": "postApiExpenses", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vatUse": { "type": "string" }, "vatType": { "type": "string" }, "clientId": { "type": "string" }, "inboxItemId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "vatRate": { "type": "number" }, "currency": { "type": "string" }, "exchangeRate": { "type": "number" }, "vendor": { "type": "string" }, "supplierVatNumber": { "type": "string" }, "category": { "type": "string" }, "contactId": { "type": "string" }, "accountId": { "type": "string" }, "productId": { "type": "string" }, "productQty": { "type": "number" }, "jobCardId": { "type": "string" }, "timeProjectId": { "type": "string" }, "rechargeable": { "type": "boolean" }, "vehicleId": { "type": "string" }, "tripId": { "type": "string" }, "costCentreId": { "type": "string" }, "analysis2Id": { "type": "string" }, "analysis3Id": { "type": "null" }, "receiptUrl": { "type": "string" }, "notes": { "type": "string" } } }, "example": { "vatUse": "taxable", "vatType": "standard", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "inboxItemId": "7c2e9b14-0a35-4f6d-8e21-5b9d3c4a1f08", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "vatRate": 15.0, "currency": "ZAR", "exchangeRate": 1.0, "vendor": "Karoo Fresh Holdings Ltd", "supplierVatNumber": "4123456789", "category": "Office supplies", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productQty": 2.0, "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rechargeable": false, "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis2Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis3Id": null, "receiptUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "accountId": { "type": "string" }, "productId": { "type": "string" }, "productQty": { "type": "number" }, "companyId": { "type": "string" }, "costCentreId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "vendor": { "type": "string" }, "supplierVatNumber": { "type": "string" }, "category": { "type": "string" }, "amount": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRate": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "receiptUrl": { "type": "string" }, "notes": { "type": "string" }, "rejectionReason": { "type": "string" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "approvedBy": { "type": "string" }, "approvedByName": { "type": "string" }, "approvedAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "ledgerNotice": { "type": "string" }, "timeProjectId": { "type": "string" }, "timeProjectName": { "type": "string" }, "rechargeable": { "type": "boolean" }, "rechargeInvoiceId": { "type": "string" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productQty": 2.0, "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "vendor": "Karoo Fresh Holdings Ltd", "supplierVatNumber": "4123456789", "category": "Office supplies", "amount": 10005.0, "vatAmount": 1305.0, "vatRate": 15.0, "currency": "ZAR", "status": "sent", "receiptUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "notes": "Budget deferred to the next financial year.", "rejectionReason": "Budget deferred to the next financial year.", "createdBy": "Thandi Mokoena", "createdByName": "Thandi Mokoena", "approvedBy": "Thandi Mokoena", "approvedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectName": "Karoo Fresh Holdings Ltd", "rechargeable": false, "rechargeInvoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/count": { "get": { "tags": [ "Expenses & claims" ], "summary": "How many expenses GET /api/expenses would page through for the same filters, so a list can say how many of how many it shows.", "operationId": "getApiExpensesCount", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "submitted,approved" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "example": "fuel" }, { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "engen" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "jobCardId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesCountResponse" }, "example": { "total": 10000 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/summary": { "get": { "tags": [ "Expenses & claims" ], "summary": "The Expenses screen's figures over every expense of the active company: how many there are, wait on an approver, are drafts and still owe a receipt, gross spend (amount + VAT) by month, category and status over the six months to asOf, and every category in use. Which statuses count as spend is the reader's rule: approved and paid claims.", "operationId": "getApiExpensesSummary", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "type": "string", "format": "date" }, "count": { "type": "integer" }, "awaitingDecision": { "type": "integer" }, "drafts": { "type": "integer" }, "missingReceipts": { "type": "integer" }, "spend": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "gross": { "type": "number" } } } }, "categories": { "type": "array", "items": { "type": "string" } } } }, "example": { "asOf": "2026-10-03", "count": 10000, "awaitingDecision": 42, "drafts": 17, "missingReceipts": 63, "spend": [ { "month": "2026-10", "category": "fuel", "status": "APPROVED", "gross": 1150.0 } ], "categories": [ "fuel", "meals", "travel" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/category-memory": { "get": { "tags": [ "Expenses & claims" ], "summary": "What Ledgr has learned about filing each supplier — the category the capture screen suggests next time, learned from how documents were actually filed, with the same sentence that screen shows. This company's memories plus the holding company's.", "operationId": "getApiExpensesCategoryMemory", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "supplier": { "type": "string" }, "category": { "type": "string" }, "timesSeen": { "type": "integer" }, "lastUsedAt": { "type": "string" }, "sentence": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplier": "Karoo Fresh Holdings Ltd", "category": "consumables", "timesSeen": 3, "lastUsedAt": "2026-09-01T08:00:00Z", "sentence": "Karoo Fresh Holdings Ltd was filed to consumables the last 3 times." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/category-memory/{id}": { "delete": { "tags": [ "Expenses & claims" ], "summary": "Forget one learned supplier, so it is no longer suggested. The next document filed from that supplier starts a new memory.", "operationId": "deleteApiExpensesCategoryMemoryById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "forgotten" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/{id}": { "get": { "tags": [ "Expenses & claims" ], "summary": "One expense with its receipt and approval trail.", "operationId": "getApiExpensesById", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiExpensesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Expenses & claims" ], "summary": "Update an expense.", "operationId": "putApiExpensesById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vatUse": { "type": "string" }, "vatType": { "type": "string" }, "date": { "type": "string", "format": "date" }, "costCentreId": { "type": "string" }, "analysis2Id": { "type": "string" }, "analysis3Id": { "type": "null" }, "description": { "type": "string" }, "amount": { "type": "number" }, "vatRate": { "type": "number" }, "vendor": { "type": "string" }, "supplierVatNumber": { "type": "string" }, "category": { "type": "string" }, "contactId": { "type": "string" }, "accountId": { "type": "string" }, "productId": { "type": "string" }, "productQty": { "type": "number" }, "receiptUrl": { "type": "string" }, "notes": { "type": "string" }, "jobCardId": { "type": "string" }, "timeProjectId": { "type": "string" }, "rechargeable": { "type": "boolean" }, "vehicleId": { "type": "string" }, "tripId": { "type": "string" } } }, "example": { "vatUse": "taxable", "vatType": "standard", "date": "2026-09-01", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis2Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis3Id": null, "description": "Consulting services — August 2026", "amount": 10005.0, "vatRate": 15.0, "vendor": "Karoo Fresh Holdings Ltd", "supplierVatNumber": "4123456789", "category": "Office supplies", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productQty": 2.0, "receiptUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "notes": "Budget deferred to the next financial year.", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rechargeable": true, "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "accountId": { "type": "string" }, "companyId": { "type": "string" }, "costCentreId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "vendor": { "type": "string" }, "supplierVatNumber": { "type": "string" }, "category": { "type": "string" }, "amount": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRate": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "receiptUrl": { "type": "string" }, "notes": { "type": "string" }, "rejectionReason": { "type": "string" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "approvedBy": { "type": "string" }, "approvedByName": { "type": "string" }, "approvedAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "ledgerNotice": { "type": "string" }, "timeProjectId": { "type": "string" }, "timeProjectName": { "type": "string" }, "rechargeable": { "type": "boolean" }, "rechargeInvoiceId": { "type": "string" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "vendor": "Karoo Fresh Holdings Ltd", "supplierVatNumber": "4123456789", "category": "Office supplies", "amount": 10005.0, "vatAmount": 1305.0, "vatRate": 15.0, "currency": "ZAR", "status": "sent", "receiptUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "notes": "Budget deferred to the next financial year.", "rejectionReason": "Budget deferred to the next financial year.", "createdBy": "Thandi Mokoena", "createdByName": "Thandi Mokoena", "approvedBy": "Thandi Mokoena", "approvedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectName": "Karoo Fresh Holdings Ltd", "rechargeable": false, "rechargeInvoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Expenses & claims" ], "summary": "Delete an expense.", "operationId": "deleteApiExpensesById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiBillsByIdResponse" }, "example": { "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/{id}/submit": { "post": { "tags": [ "Expenses & claims" ], "summary": "Submit for approval.", "operationId": "postApiExpensesByIdSubmit", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiExpensesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/{id}/approve": { "post": { "tags": [ "Expenses & claims" ], "summary": "Approve. This is a write transaction that runs a full GL posting, so it goes through dbQuery rather than on the request thread.", "operationId": "postApiExpensesByIdApprove", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiExpensesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/{id}/reject": { "post": { "tags": [ "Expenses & claims" ], "summary": "Reject, with a reason.", "operationId": "postApiExpensesByIdReject", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdRejectRequest" }, "example": { "reason": "No VAT invoice attached" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiExpensesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/{id}/pay": { "post": { "tags": [ "Expenses & claims" ], "summary": "Record the reimbursement. Posts the payment as its own entry (DR 2120 / CR the account named by bankAccountId) on `date` - the day the money left; today when absent, never before the claim, never after today - beside the approval accrual that stays in the claim's own month, so a claim from a closed month can be paid in an open one.", "operationId": "postApiExpensesByIdPay", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiExpensesByIdPayRequest" }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiExpensesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/receipts": { "post": { "tags": [ "Expenses & claims" ], "summary": "Upload a receipt image. The bytes go to object storage; the row holds the reference.", "operationId": "postApiExpensesReceipts", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiExpensesReceiptsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiExpensesReceiptsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/receipts/{id}": { "get": { "tags": [ "Expenses & claims" ], "summary": "The legacy base64 receipt read path, kept until the attachment backfill finishes. New code should use GET /api/files/{id}.", "operationId": "getApiExpensesReceiptsById", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiExpensesReceiptsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiExpensesReceiptsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/ocr": { "post": { "tags": [ "Expenses & claims" ], "summary": "Run Tesseract over a receipt and return the legacy field shape.", "operationId": "postApiExpensesOcr", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/categories": { "get": { "tags": [ "Expenses & claims" ], "summary": "The categories expenses and bills are filed against. Needs expenses:view and the Expenses module, not Inventory.", "operationId": "getApiExpensesCategories", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiExpensesCategoriesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "fuel-and-tolls", "name": "Fuel and tolls", "color": "#0D47A1", "icon": "fuel", "sortOrder": 0, "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "productCount": 0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Expenses & claims" ], "summary": "Add an expense category. The code is derived from the name when left blank. Needs expenses:create and the Expenses module, not Inventory.", "operationId": "postApiExpensesCategories", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "sortOrder": { "type": "integer" }, "accountCode": { "type": "string" } } }, "example": { "code": "", "name": "Fuel and tolls", "color": "#0D47A1", "description": "Fuel, e-tolls and parking for business trips", "icon": "fuel", "sortOrder": 0, "accountCode": "6190" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiExpensesCategoriesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiExpensesCategoriesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/category-bookings": { "get": { "tags": [ "Expenses & claims" ], "summary": "Where a document filed under each category word books: the tenant's categories, the built-ins and the words its expenses and bills already carry. booksToFallback is true where nothing maps the word and it lands in 6340 Sundry Expenses. Needs expenses:view and the Expenses module.", "operationId": "getApiExpensesCategoryBookings", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "accountCode": { "type": "string" }, "accountName": { "type": "string" }, "booksToFallback": { "type": "boolean" } } } }, "example": [ { "category": "repairs", "accountCode": "6180", "accountName": "Repairs & Maintenance", "booksToFallback": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/categories/{id}": { "put": { "tags": [ "Expenses & claims" ], "summary": "Edit an expense category, above all the expense account it books to (a blank accountCode clears it). The same edit as PUT /api/inventory/categories/{id}, under the Expenses module: needs expenses:edit, not Inventory.", "operationId": "putApiExpensesCategoriesById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiExpensesCategoriesByIdRequest" }, "example": { "code": "fuel-and-tolls", "name": "Fuel and tolls", "color": "#0D47A1", "icon": "fuel", "description": "Fuel, e-tolls and parking for business trips", "sortOrder": 0, "isActive": true, "accountCode": "6190" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiExpensesCategoriesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiExpensesCategoriesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/category-budgets": { "get": { "tags": [ "Expenses & claims" ], "summary": "Budget against actual per expense category.", "operationId": "getApiExpensesCategoryBudgets", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiExpensesCategoryBudgetsResponseItem" } }, "example": [ { "category": "Office supplies", "monthlyBudget": 1.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/category-budgets/{category}": { "put": { "tags": [ "Expenses & claims" ], "summary": "Set a category's monthly budget.", "operationId": "putApiExpensesCategoryBudgetsByCategory", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "category", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "monthlyBudget": { "type": "number" } } }, "example": { "monthlyBudget": 15000.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesCategoryBudgetsResponseItem" }, "example": { "category": "Office supplies", "monthlyBudget": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/ocr": { "get": { "tags": [ "Expenses & claims" ], "summary": "Documents already scanned, with per-field confidence, provenance and raw text.", "operationId": "getApiDocumentsOcr", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "expenseId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "billId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiDocumentsOcrResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiDocumentsOcrResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Expenses & claims" ], "summary": "Scan a receipt, supplier invoice or statement — PDF, JPEG, PNG or multi-page TIFF. Unlike /api/expenses/ocr this returns confidence and provenance per field, not just values.", "operationId": "postApiDocumentsOcr", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "example": "receipt" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "example": "ZAR" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiDocumentsOcrResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiDocumentsOcrResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/inbox": { "get": { "tags": [ "Expenses & claims" ], "summary": "The document inbox: everything uploaded in bulk or emailed in, newest first, with what the reader made of each.", "operationId": "getApiDocumentsInbox", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "open" }, { "name": "offset", "in": "query", "required": false, "description": "How many rows to skip. Use with `limit` to page. A paged response reports `total`, which is the number of rows matching the filter rather than the number returned.", "schema": { "type": "integer" }, "example": "0" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiDocumentsInboxByIdResponseItem" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "counts": { "$ref": "#/components/schemas/GetApiDocumentsInboxResponseCounts" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "source": "referral", "status": "sent", "documentKind": "standard", "fileName": "SignedPO-4417.pdf", "contentType": "application/pdf", "sizeBytes": 1, "pageCount": 3, "supplierName": "Karoo Fresh Holdings Ltd", "documentDate": "2026-09-01", "totalAmount": 10005.0, "currency": "ZAR", "confidence": 1, "exactText": false, "fromEmail": "accounts@karoofresh.example", "subject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "receivedAt": "2026-09-01T09:15:00Z", "expenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "duplicateOfId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "duplicateNote": "Budget deferred to the next financial year.", "error": "text", "fileUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "splitFromId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "splitIndex": 1, "splitCount": 3, "splitNote": "Budget deferred to the next financial year.", "statementAccountRef": "INV-0001", "statementStart": "2026-09-01", "statementEnd": "2026-09-30", "statementTransactionCount": 3, "statementImported": 1, "statementDuplicates": 1, "statementBalances": true, "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountName": "Karoo Fresh Holdings Ltd", "statementNote": "Budget deferred to the next financial year." } ], "total": 42, "limit": 50, "offset": 0, "counts": { "key": 3 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Expenses & claims" ], "summary": "Drop documents in. Multipart, several files at a time; answers immediately and reads them off the request.", "operationId": "postApiDocumentsInbox", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "example": "receipt" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "integer" }, "rejected": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiDocumentsInboxByIdResponseItem" } }, "errors": { "type": "array", "items": { "type": "object" } } } }, "example": { "accepted": 1, "rejected": 0, "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "source": "referral", "status": "sent", "documentKind": "standard", "fileName": "SignedPO-4417.pdf", "contentType": "application/pdf", "sizeBytes": 1, "pageCount": 3, "supplierName": "Karoo Fresh Holdings Ltd", "documentDate": "2026-09-01", "totalAmount": 10005.0, "currency": "ZAR", "confidence": 1, "exactText": false, "fromEmail": "accounts@karoofresh.example", "subject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "receivedAt": "2026-09-01T09:15:00Z", "expenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "duplicateOfId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "duplicateNote": "Budget deferred to the next financial year.", "error": "text", "fileUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "splitFromId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "splitIndex": 1, "splitCount": 3, "splitNote": "Budget deferred to the next financial year.", "statementAccountRef": "INV-0001", "statementStart": "2026-09-01", "statementEnd": "2026-09-30", "statementTransactionCount": 3, "statementImported": 1, "statementDuplicates": 1, "statementBalances": true, "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountName": "Karoo Fresh Holdings Ltd", "statementNote": "Budget deferred to the next financial year." } ], "errors": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/inbox/{id}": { "get": { "tags": [ "Expenses & claims" ], "summary": "One item's full reading, plus what this tenant's own history says to file it as.", "operationId": "getApiDocumentsInboxById", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/GetApiDocumentsInboxByIdResponseItem" }, "extraction": { "$ref": "#/components/schemas/GetApiDocumentsOcrResponseExtraction" }, "rawText": { "type": "string" }, "suggestion": { "$ref": "#/components/schemas/GetApiDocumentsOcrResponseSuggestion" }, "bankAccounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "accountNumberHint": { "type": "string" }, "currency": { "type": "string" }, "matchesStatement": { "type": "boolean" } } } } } }, "example": { "item": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "source": "referral", "status": "sent", "documentKind": "standard", "fileName": "SignedPO-4417.pdf", "contentType": "application/pdf", "sizeBytes": 1, "pageCount": 3, "supplierName": "Karoo Fresh Holdings Ltd", "documentDate": "2026-09-01", "totalAmount": 10005.0, "currency": "ZAR", "confidence": 1, "exactText": false, "fromEmail": "accounts@karoofresh.example", "subject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "receivedAt": "2026-09-01T09:15:00Z", "expenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "duplicateOfId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "duplicateNote": "Budget deferred to the next financial year.", "error": "text", "fileUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "splitFromId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "splitIndex": 1, "splitCount": 3, "splitNote": "Budget deferred to the next financial year.", "statementAccountRef": "INV-0001", "statementStart": "2026-09-01", "statementEnd": "2026-09-30", "statementTransactionCount": 3, "statementImported": 1, "statementDuplicates": 1, "statementBalances": true, "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountName": "Karoo Fresh Holdings Ltd", "statementNote": "Budget deferred to the next financial year." }, "extraction": { "supplierName": "Karoo Fresh Holdings Ltd", "supplierVatNumber": "4123456789", "documentNumber": "INV-0001", "documentDate": "2026-09-01", "subtotal": 8700.0, "vatAmount": 1305.0, "vatRatePercent": 15.0, "total": 10005.0, "currency": "ZAR", "categoryHint": "text", "litres": 1.0, "lineItems": [ { "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "amount": 10005.0, "confidence": 1 } ], "fields": [ { "name": "Karoo Fresh Holdings Ltd", "confidence": 1, "source": "referral", "evidence": "text" } ], "reconciliation": { "subtotalPlusVatMatchesTotal": true, "impliedVatRatePercent": 15.0, "vatRateRecognised": true, "discrepancy": 1.0, "lineItemsSum": 1.0, "lineItemsMatchSubtotal": true }, "overallConfidence": 1, "engineConfidence": 1, "engineScored": false, "warnings": [], "droppedLowConfidence": [ "text" ], "manualEntryRequired": true }, "rawText": "text", "suggestion": { "category": "Office supplies", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reason": "Budget deferred to the next financial year." }, "bankAccounts": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "accountNumberHint": "62012345678", "currency": "ZAR", "matchesStatement": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/inbox/{id}/thumbnail": { "get": { "tags": [ "Expenses & claims" ], "summary": "A small JPEG of the document — a photograph shrunk, or a PDF's first page — for the Inbox row. 404 when there is nothing that can be drawn.", "operationId": "getApiDocumentsInboxByIdThumbnail", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A file download.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/inbox/{id}/retry": { "post": { "tags": [ "Expenses & claims" ], "summary": "Put a failed item back in the reading queue.", "operationId": "postApiDocumentsInboxByIdRetry", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/inbox/{id}/unsplit": { "post": { "tags": [ "Expenses & claims" ], "summary": "Put a page that was split into several documents back together: the crops are discarded and the whole page is read again as one.", "operationId": "postApiDocumentsInboxByIdUnsplit", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "discarded": { "type": "integer" } } }, "example": { "ok": true, "discarded": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/inbox/{id}/discard": { "post": { "tags": [ "Expenses & claims" ], "summary": "Throw an inbox item away without filing it.", "operationId": "postApiDocumentsInboxByIdDiscard", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/inbox/{id}/import-statement": { "post": { "tags": [ "Expenses & claims" ], "summary": "Import an emailed bank statement into the account you choose. Held statements are the ones that read perfectly but could not prove which account they belong to, or did not add up to the closing balance the bank printed. Gated on banking:create, not expenses — this writes bank transactions.", "operationId": "postApiDocumentsInboxByIdImportStatement", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankAccountId": { "type": "string" }, "confirmDifferentAccount": { "type": "boolean" }, "saveAccountNumber": { "type": "boolean" }, "confirmRowDoubts": { "type": "boolean" } } }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "confirmDifferentAccount": false, "saveAccountNumber": false, "confirmRowDoubts": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "integer" }, "duplicates": { "type": "integer" }, "total": { "type": "integer" }, "bankAccountId": { "type": "string" }, "bankAccountName": { "type": "string" }, "message": { "type": "string" } } }, "example": { "imported": 1, "duplicates": 1, "total": 2, "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountName": "Karoo Fresh Holdings Ltd", "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/inbox/{id}/link": { "post": { "tags": [ "Expenses & claims" ], "summary": "Attach an inbox item to the expense or bill it became, and remember how this supplier gets filed.", "operationId": "postApiDocumentsInboxByIdLink", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expenseId": { "type": "string" }, "billId": { "type": "string" }, "category": { "type": "string" }, "contactId": { "type": "string" } } }, "example": { "expenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "category": "fuel", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/inbox/address": { "get": { "tags": [ "Expenses & claims" ], "summary": "This company's email-in address. Minted on first ask; absent when the deployment cannot receive email.", "operationId": "getApiDocumentsInboxAddress", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiDocumentsInboxAddressResponse" }, "example": { "configured": false, "address": "12 Long Street, Cape Town, 8001", "note": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/inbox/address/rotate": { "post": { "tags": [ "Expenses & claims" ], "summary": "Issue a new email-in address. The previous one stops working immediately.", "operationId": "postApiDocumentsInboxAddressRotate", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiDocumentsInboxAddressResponse" }, "example": { "configured": false, "address": "12 Long Street, Cape Town, 8001", "note": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/ocr/{id}/link": { "post": { "tags": [ "Expenses & claims" ], "summary": "Attach a scan to the expense or bill it turned into.", "operationId": "postApiDocumentsOcrByIdLink", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expenseId": { "type": "string" }, "billId": { "type": "string" } } }, "example": { "expenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills": { "get": { "tags": [ "Expenses & claims" ], "summary": "Supplier invoices.", "operationId": "getApiBills", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "due" }, { "name": "jobCardId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "submitted", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" }, { "name": "approval", "in": "query", "required": false, "schema": { "type": "string" }, "example": "awaiting" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBillsResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendor": "Karoo Fresh Holdings Ltd", "billNumber": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "amount": 10005.0, "vatAmount": 1305.0, "vatRate": 15.0, "currency": "ZAR", "category": "Office supplies", "status": "sent", "recurring": false, "frequency": "monthly", "nextDate": "2026-09-01", "endDate": "2026-09-30", "recurrenceActive": true, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "paidAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "discountRate": 0.0, "discountFixed": 0.0, "lineTotal": 10005.0, "vatAmount": 1305.0, "category": "Office supplies", "customsReference": null, "openMarketValue": null } ], "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "sellerDeclarationUrl": null, "sellerDeclarationSignedOn": null } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Expenses & claims" ], "summary": "Capture a supplier invoice.", "operationId": "postApiBills", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approve": { "type": "null" }, "clientId": { "type": "string" }, "inboxItemId": { "type": "string" }, "vendor": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "vatRate": { "type": "number" }, "currency": { "type": "string" }, "exchangeRate": { "type": "number" }, "billNumber": { "type": "string" }, "contactId": { "type": "string" }, "companyId": { "type": "null" }, "costCentreId": { "type": "string" }, "analysis2Id": { "type": "string" }, "analysis3Id": { "type": "null" }, "category": { "type": "string" }, "recurring": { "type": "boolean" }, "frequency": { "type": "string" }, "endDate": { "type": "string", "format": "date" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "jobCardId": { "type": "string" }, "vehicleId": { "type": "string" }, "tripId": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBillsRequestLinesItem" } }, "purchaseOrderId": { "type": "string" }, "rentedLeaseId": { "type": "string" } } }, "example": { "approve": null, "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "inboxItemId": "7c2e9b14-0a35-4f6d-8e21-5b9d3c4a1f08", "vendor": "Karoo Fresh Holdings Ltd", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "amount": 10005.0, "vatRate": 15.0, "currency": "ZAR", "exchangeRate": 1.0, "billNumber": "INV-0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": null, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis2Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis3Id": null, "category": "Office supplies", "recurring": false, "frequency": "monthly", "endDate": "2026-09-30", "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "discountRate": 0.0, "discountFixed": 0.0, "lineTotal": 10005.0, "vatAmount": 1305.0, "category": "Office supplies", "customsReference": null, "openMarketValue": null } ], "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rentedLeaseId": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBillsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/{id}": { "get": { "tags": [ "Expenses & claims" ], "summary": "One bill with its lines and payments.", "operationId": "getApiBillsById", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "contactId": { "type": "string" }, "companyId": { "type": "string" }, "costCentreId": { "type": "string" }, "vendor": { "type": "string" }, "billNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRate": { "type": "number" }, "currency": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "recurring": { "type": "boolean" }, "frequency": { "type": "string" }, "nextDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "recurrenceActive": { "type": "boolean" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "paidAt": { "type": "string" }, "jobCardId": { "type": "string" }, "jobNumber": { "type": "string" }, "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBillsRequestLinesItem" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "ledgerNotice": { "type": "string" }, "sellerDeclarationUrl": { "type": "null" }, "sellerDeclarationSignedOn": { "type": "null" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendor": "Karoo Fresh Holdings Ltd", "billNumber": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "amount": 10005.0, "vatAmount": 1305.0, "vatRate": 15.0, "currency": "ZAR", "category": "Office supplies", "status": "sent", "recurring": false, "frequency": "monthly", "nextDate": "2026-09-01", "endDate": "2026-09-30", "recurrenceActive": true, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "paidAt": "2026-09-01T09:15:00Z", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobNumber": "JC-0001", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "discountRate": 0.0, "discountFixed": 0.0, "lineTotal": 10005.0, "vatAmount": 1305.0, "category": "Office supplies", "customsReference": null, "openMarketValue": null } ], "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "sellerDeclarationUrl": null, "sellerDeclarationSignedOn": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Expenses & claims" ], "summary": "Update a bill.", "operationId": "putApiBillsById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "exchangeRate": { "type": "number" }, "vendor": { "type": "string" }, "costCentreId": { "type": "string" }, "analysis2Id": { "type": "string" }, "analysis3Id": { "type": "null" }, "billNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "vatRate": { "type": "number" }, "currency": { "type": "string" }, "contactId": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "recurring": { "type": "boolean" }, "frequency": { "type": "string" }, "endDate": { "type": "string", "format": "date" }, "recurrenceActive": { "type": "boolean" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "jobCardId": { "type": "string" }, "vehicleId": { "type": "string" }, "tripId": { "type": "string" }, "purchaseOrderId": { "type": "string" }, "rentedLeaseId": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBillsRequestLinesItem" } } } }, "example": { "exchangeRate": 18.5, "vendor": "Karoo Fresh Holdings Ltd", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis2Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis3Id": null, "billNumber": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "amount": 10005.0, "vatRate": 15.0, "currency": "ZAR", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "category": "Office supplies", "status": "sent", "recurring": true, "frequency": "monthly", "endDate": "2026-09-30", "recurrenceActive": true, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rentedLeaseId": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "discountRate": 0.0, "discountFixed": 0.0, "lineTotal": 10005.0, "vatAmount": 1305.0, "category": "Office supplies", "customsReference": null, "openMarketValue": null } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBillsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Expenses & claims" ], "summary": "Delete a bill.", "operationId": "deleteApiBillsById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiBillsByIdResponse" }, "example": { "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/{id}/pay": { "post": { "tags": [ "Expenses & claims" ], "summary": "Record a payment against a bill. Send date (yyyy-MM-dd) for the day the money left - not before the bill, not after today, and not inside a filed VAT201 period on the payments basis, where the input tax is claimed in the month it is paid. A foreign bill settles at the exchangeRate sent, else at the rate on file for the day it is paid, and the difference from the rate it was booked at is booked as an exchange gain or loss (IFRS for SMEs 30.10); with no rate on file it settles at the bill's own.", "operationId": "postApiBillsByIdPay", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "exchangeRate": { "type": "number" }, "clientId": { "type": "string" }, "bankAccountId": { "type": "string" } } }, "example": { "date": "2026-09-25", "exchangeRate": 18.5, "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBillsResponseItem" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendor": "Karoo Fresh Holdings Ltd", "billNumber": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "amount": 10005.0, "vatAmount": 1305.0, "vatRate": 15.0, "currency": "ZAR", "category": "Office supplies", "status": "sent", "recurring": false, "frequency": "monthly", "nextDate": "2026-09-01", "endDate": "2026-09-30", "recurrenceActive": true, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "paidAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "discountRate": 0.0, "discountFixed": 0.0, "lineTotal": 10005.0, "vatAmount": 1305.0, "category": "Office supplies", "customsReference": null, "openMarketValue": null } ], "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "sellerDeclarationUrl": null, "sellerDeclarationSignedOn": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/{id}/payments": { "post": { "tags": [ "Expenses & claims" ], "summary": "Pay part of a bill, or set a supplier prepayment against it. An instalment is money out of bankAccountId (or the pooled bank) on date, never before the bill's own date and never after today, and posts its own journal at that date: the bill owes what is left. A foreign bill's instalment settles at exchangeRate, else at the rate on file for date, and books the exchange difference. The instalment that leaves nothing owing settles the bill. With prepaymentId, that prepayment is set against the bill (amount absent takes as much as the bill still owes) and no money moves. Refused for more than is still owed, an unapproved bill and one a three-way-match exception holds.", "operationId": "postApiBillsByIdPayments", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" }, "date": { "type": "string", "format": "date" }, "bankAccountId": { "type": "string" }, "exchangeRate": { "type": "null" }, "reference": { "type": "string" }, "prepaymentId": { "type": "null" } } }, "example": { "amount": 400.0, "date": "2026-09-20", "bankAccountId": "8d2e4b17-6c3a-4f90-b5e1-7a9c0d3f2b64", "exchangeRate": null, "reference": "EFT 4471", "prepaymentId": null } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdPaymentsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBillsByIdPaymentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Expenses & claims" ], "summary": "What has been paid on a bill: each instalment, prepayment set against it and part contra, oldest first.", "operationId": "getApiBillsByIdPayments", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBillsByIdPaymentsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiBillsByIdPaymentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/{id}/payments/{paymentId}": { "delete": { "tags": [ "Expenses & claims" ], "summary": "Take an instalment or an allocated prepayment back off a bill that is not yet paid. The instalment's journal is reversed; a prepayment is free to be set against another bill. Refused on a paid bill (mark it unpaid first) and for a part contra.", "operationId": "deleteApiBillsByIdPaymentsByPaymentId", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdPaymentsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBillsByIdPaymentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/suppliers/{id}/prepayments": { "post": { "tags": [ "Expenses & claims" ], "summary": "Money paid to a supplier before their bill. It sits as a debit balance on the supplier in trade payables, shows as a negative line on their statement and in aged creditors, and is set against a bill later with POST /api/bills/{id}/payments and its prepaymentId. In the company's own currency.", "operationId": "postApiSuppliersByIdPrepayments", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" }, "date": { "type": "string", "format": "date" }, "bankAccountId": { "type": "string" }, "reference": { "type": "string" } } }, "example": { "amount": 300.0, "date": "2026-09-10", "bankAccountId": "8d2e4b17-6c3a-4f90-b5e1-7a9c0d3f2b64", "reference": "Advance on order" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBillsByIdPaymentsResponseItem" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "amount": 10005.0, "currency": "ZAR", "method": "eft", "reference": "INV-0001", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "remaining": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Expenses & claims" ], "summary": "A supplier's prepayments, oldest first, each with what is not yet set against a bill. Paged: limit (default 200, at most 500) and offset.", "operationId": "getApiSuppliersByIdPrepayments", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBillsByIdPaymentsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiBillsByIdPaymentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/suppliers/{id}/prepayments/{paymentId}": { "delete": { "tags": [ "Expenses & claims" ], "summary": "Withdraw a prepayment no bill has taken. Its journal is reversed. Refused once any of it is set against a bill.", "operationId": "deleteApiSuppliersByIdPrepaymentsByPaymentId", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mileage/trips": { "get": { "tags": [ "Expenses & claims" ], "summary": "Logged trips with their calculated claim.", "operationId": "getApiMileageTrips", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMileageTripsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripDate": "2026-09-01", "origin": "sale", "destination": "accounts@karoofresh.example", "distanceKm": 1.0, "ratePerKm": 1.0, "claimAmount": 10005.0, "purpose": "sale", "vehicle": "CA 123-456", "status": "sent", "createdBy": "Thandi Mokoena", "createdByName": "Thandi Mokoena", "approvedBy": "Thandi Mokoena", "approvedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Expenses & claims" ], "summary": "Log a trip. The rate is year-keyed on SarsTravelRates and resolved from the trip's own date — R4.95/km for 2026/27, R4.76/km for 2025/26.", "operationId": "postApiMileageTrips", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "tripDate": { "type": "string", "format": "date" }, "origin": { "type": "string" }, "destination": { "type": "string" }, "distanceKm": { "type": "number" }, "ratePerKm": { "type": "number" }, "purpose": { "type": "string" }, "vehicle": { "type": "string" }, "notes": { "type": "string" }, "contactId": { "type": "string" }, "costCentreId": { "type": "string" } } }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripDate": "2026-09-30", "origin": "sale", "destination": "accounts@karoofresh.example", "distanceKm": 145.0, "ratePerKm": 1.0, "purpose": "Site inspection", "vehicle": "CA 123-456", "notes": "Budget deferred to the next financial year.", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMileageTripsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMileageTripsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mileage/trips/{id}": { "put": { "tags": [ "Expenses & claims" ], "summary": "Correct a trip.", "operationId": "putApiMileageTripsById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tripDate": { "type": "string", "format": "date" }, "origin": { "type": "string" }, "destination": { "type": "string" }, "distanceKm": { "type": "number" }, "ratePerKm": { "type": "number" }, "purpose": { "type": "string" }, "vehicle": { "type": "string" }, "status": { "type": "string" }, "notes": { "type": "string" }, "contactId": { "type": "string" }, "clearContactId": { "type": "boolean" }, "costCentreId": { "type": "string" } } }, "example": { "tripDate": "2026-09-01", "origin": "sale", "destination": "accounts@karoofresh.example", "distanceKm": 64.0, "ratePerKm": 1.0, "purpose": "sale", "vehicle": "CA 123-456", "status": "sent", "notes": "Budget deferred to the next financial year.", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clearContactId": false, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMileageTripsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMileageTripsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Expenses & claims" ], "summary": "Delete a trip.", "operationId": "deleteApiMileageTripsById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/per-diem/claims": { "get": { "tags": [ "Expenses & claims" ], "summary": "Travel allowance claims.", "operationId": "getApiPerDiemClaims", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPerDiemClaimsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employee": "Thandi Mokoena", "destination": "accounts@karoofresh.example", "periodLabel": "2026-09", "days": 30, "ratePerDay": 1.0, "totalAmount": 10005.0, "policy": "fifo", "status": "sent", "rejectionReason": "Budget deferred to the next financial year.", "createdBy": "Thandi Mokoena", "createdByName": "Thandi Mokoena", "approvedBy": "Thandi Mokoena", "approvedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Expenses & claims" ], "summary": "Raise a per diem claim.", "operationId": "postApiPerDiemClaims", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "employee": { "type": "string" }, "destination": { "type": "string" }, "periodLabel": { "type": "string" }, "fromDate": { "type": "string", "format": "date" }, "toDate": { "type": "string", "format": "date" }, "tripKind": { "type": "string" }, "days": { "type": "integer" }, "rateId": { "type": "string" }, "ratePerDay": { "type": "number" }, "notes": { "type": "string" }, "country": { "type": "string" }, "costCentreId": { "type": "string" } } }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employee": "Thandi Mokoena", "destination": "accounts@karoofresh.example", "periodLabel": "2026-09", "fromDate": "2026-09-01", "toDate": "2026-09-30", "tripKind": "overnight", "days": 30, "rateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ratePerDay": 15.0, "notes": "Budget deferred to the next financial year.", "country": "United Kingdom", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPerDiemClaimsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPerDiemClaimsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/per-diem/claims/{id}": { "put": { "tags": [ "Expenses & claims" ], "summary": "Update a claim.", "operationId": "putApiPerDiemClaimsById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rateId": { "type": "string" }, "employee": { "type": "string" }, "destination": { "type": "string" }, "periodLabel": { "type": "string" }, "fromDate": { "type": "string", "format": "date" }, "toDate": { "type": "string", "format": "date" }, "tripKind": { "type": "string" }, "days": { "type": "integer" }, "ratePerDay": { "type": "number" }, "status": { "type": "string" }, "notes": { "type": "string" }, "country": { "type": "string" }, "costCentreId": { "type": "string" } } }, "example": { "rateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employee": "Thandi Mokoena", "destination": "accounts@karoofresh.example", "periodLabel": "2026-09", "fromDate": "2026-09-01", "toDate": "2026-09-03", "tripKind": "overnight", "days": 3, "ratePerDay": 1.0, "status": "sent", "notes": "Budget deferred to the next financial year.", "country": "United Kingdom", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPerDiemClaimsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPerDiemClaimsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Expenses & claims" ], "summary": "Delete a claim.", "operationId": "deleteApiPerDiemClaimsById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/per-diem/claims/{id}/approve": { "post": { "tags": [ "Expenses & claims" ], "summary": "Approve a claim.", "operationId": "postApiPerDiemClaimsByIdApprove", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPerDiemClaimsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPerDiemClaimsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/per-diem/claims/{id}/reject": { "post": { "tags": [ "Expenses & claims" ], "summary": "Reject a claim, with a reason.", "operationId": "postApiPerDiemClaimsByIdReject", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdRejectRequest" }, "example": { "reason": "Dates overlap an existing claim" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPerDiemClaimsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPerDiemClaimsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/per-diem/claims/{id}/pay": { "post": { "tags": [ "Expenses & claims" ], "summary": "Record payment of a claim, on `date` (the day the money left; today when absent, never before the claim, never after today) as its own entry beside the approval accrual.", "operationId": "postApiPerDiemClaimsByIdPay", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiExpensesByIdPayRequest" }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPerDiemClaimsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPerDiemClaimsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/per-diem/rates": { "get": { "tags": [ "Expenses & claims" ], "summary": "The company's own per-diem rates — the only rates a claim may be raised at.", "operationId": "getApiPerDiemRates", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPerDiemRatesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "dailyAmount": 10005.0, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Expenses & claims" ], "summary": "Add a per-diem rate (expenses:approve).", "operationId": "postApiPerDiemRates", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPerDiemRatesRequest" }, "example": { "name": "Overnight, local", "dailyAmount": 650.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPerDiemRatesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "dailyAmount": 10005.0, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/per-diem/rates/{id}": { "put": { "tags": [ "Expenses & claims" ], "summary": "Change a per-diem rate. Claims already raised keep the rate they were raised at.", "operationId": "putApiPerDiemRatesById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPerDiemRatesRequest" }, "example": { "name": "Overnight, local", "dailyAmount": 700.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPerDiemRatesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "dailyAmount": 10005.0, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Expenses & claims" ], "summary": "Remove a per-diem rate. Claims already raised keep the rate they were raised at.", "operationId": "deleteApiPerDiemRatesById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/petty-cash": { "get": { "tags": [ "Expenses & claims" ], "summary": "The float and its transactions.", "operationId": "getApiPettyCash", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "floatAmount": { "type": "number" }, "balance": { "type": "number" }, "txns": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPettyCashTxnsResponse" } } } }, "example": { "floatAmount": 10005.0, "balance": 10005.0, "txns": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "category": "Office supplies", "receipt": false, "createdBy": "Thandi Mokoena", "createdByName": "Thandi Mokoena", "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/petty-cash/float": { "put": { "tags": [ "Expenses & claims" ], "summary": "Set the float: the tin is topped back up to it, drawing (or paying back) the difference from the bank.", "operationId": "putApiPettyCashFloat", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "floatAmount": { "type": "number" }, "bankAccountId": { "type": "string" }, "bankTransactionId": { "type": "null" }, "date": { "type": "string", "format": "date" } } }, "example": { "floatAmount": 1500.0, "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankTransactionId": null, "date": "2026-09-01" } } } }, "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/petty-cash/counts": { "post": { "tags": [ "Expenses & claims" ], "summary": "Count the tin: the cash found against the books. The difference is booked to Sundry Expenses and the tin holds what was counted.", "operationId": "postApiPettyCashCounts", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "countedAmount": { "type": "number" }, "date": { "type": "string", "format": "date" }, "note": { "type": "string" } } }, "example": { "countedAmount": 720.0, "date": "2026-09-01", "note": "Month-end count" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPettyCashCountsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "countedAmount": 720.0, "bookAmount": 730.0, "difference": -10.0, "note": "Month-end count", "createdAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Expenses & claims" ], "summary": "The counts of the tin, newest first and 100 at a time (`?limit=` up to 500, `?offset=` for older ones): the cash counted, what the books held, and the difference.", "operationId": "getApiPettyCashCounts", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPettyCashCountsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "countedAmount": 720.0, "bookAmount": 730.0, "difference": -10.0, "note": "Month-end count", "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/petty-cash/txns": { "post": { "tags": [ "Expenses & claims" ], "summary": "Record a petty-cash payment or receipt.", "operationId": "postApiPettyCashTxns", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vatAmount": { "type": "number" }, "supplierVatNumber": { "type": "string" }, "clientId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "category": { "type": "string" }, "receipt": { "type": "boolean" }, "notes": { "type": "string" }, "costCentreId": { "type": "string" } } }, "example": { "vatAmount": 13.04, "supplierVatNumber": "4210102051", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-08-19", "description": "Courier", "amount": 145.0, "category": "Postage", "receipt": false, "notes": "Budget deferred to the next financial year.", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPettyCashTxnsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPettyCashTxnsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/petty-cash/txns/{id}": { "put": { "tags": [ "Expenses & claims" ], "summary": "Correct a petty-cash transaction.", "operationId": "putApiPettyCashTxnsById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vatAmount": { "type": "number" }, "supplierVatNumber": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "category": { "type": "string" }, "receipt": { "type": "boolean" }, "notes": { "type": "string" }, "costCentreId": { "type": "string" } } }, "example": { "vatAmount": 13.04, "supplierVatNumber": "4210102051", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 150.0, "category": "Office supplies", "receipt": true, "notes": "Budget deferred to the next financial year.", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPettyCashTxnsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPettyCashTxnsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Expenses & claims" ], "summary": "Delete a petty-cash transaction.", "operationId": "deleteApiPettyCashTxnsById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/{id}/reopen": { "post": { "tags": [ "Expenses & claims" ], "summary": "Un-pay a claim: PAID back to APPROVED, reversing the cash leg to the accrual. Needs expenses:approve, because it undoes a payment decision. Added with the settlement guard and required by it — refusing to edit a paid claim would otherwise be a dead end, as this module had no way back from PAID at all.", "operationId": "postApiExpensesByIdReopen", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiExpensesByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mileage/trips/{id}/submit": { "post": { "tags": [ "Expenses & claims" ], "summary": "Submit a logged trip for approval. The claimant's own act, so expenses:create rather than approve.", "operationId": "postApiMileageTripsByIdSubmit", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMileageTripsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMileageTripsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mileage/trips/{id}/approve": { "post": { "tags": [ "Expenses & claims" ], "summary": "Approve a trip. Posts DR 6280 Mileage Reimbursement / CR 2120 Accruals at the cent-rounded claim. Needs expenses:approve — before these endpoints existed the only way to write a status was PUT, which took any string on expenses:edit.", "operationId": "postApiMileageTripsByIdApprove", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMileageTripsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMileageTripsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mileage/trips/{id}/reject": { "post": { "tags": [ "Expenses & claims" ], "summary": "Reject a trip, or take an approval back before the money goes out, with a reason (required). Reverses any posting. Needs expenses:approve.", "operationId": "postApiMileageTripsByIdReject", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdRejectRequest" }, "example": { "reason": "Trip was for a personal errand" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMileageTripsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMileageTripsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mileage/trips/{id}/pay": { "post": { "tags": [ "Expenses & claims" ], "summary": "Mark a trip reimbursed. Posts the payment as its own entry (DR 2120 / CR the account named by bankAccountId, with a bank line on it; the pooled 1350 when none is named) on `date` - the day the money left; today when absent, never before the trip, never after today - beside the approval accrual. Only from approved, and terminal — a paid trip can no longer be edited. Needs expenses:approve.", "operationId": "postApiMileageTripsByIdPay", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiExpensesByIdPayRequest" }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMileageTripsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMileageTripsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/documents/inbox/{id}/bank-line-proposals": { "get": { "tags": [ "Expenses & claims" ], "summary": "Unmatched bank lines of the same amount within a few days of this document. Proposals; nothing is filed.", "operationId": "getApiDocumentsInboxByIdBankLineProposals", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "bankTransactionId": { "type": "string" }, "bankAccountId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "daysApart": { "type": "integer" }, "sentence": { "type": "string" } } } }, "example": [ { "bankTransactionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "OCEAN BASKET SANDTON", "amount": 1850.0, "daysApart": 2, "sentence": "Ocean Basket is for the same amount and is dated 2 days earlier. Attach it to this line?" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/{id}/approve": { "post": { "tags": [ "Expenses & claims" ], "summary": "Approve a bill for payment. Needs expenses:approve; refused when it is paid, void, a credit note or already approved.", "operationId": "postApiBillsByIdApprove", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdRejectResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBillsByIdRejectResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/{id}/reject": { "post": { "tags": [ "Expenses & claims" ], "summary": "Send a bill back, with a reason. It stays owed and cannot be paid until it is corrected (which sends it back for approval) or voided.", "operationId": "postApiBillsByIdReject", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdRejectRequest" }, "example": { "reason": "Not our order — delivered to the wrong site" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdRejectResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBillsByIdRejectResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/approval-limits": { "get": { "tags": [ "Expenses & claims" ], "summary": "How much each role or person may approve in the active company. A person's own limit wins over their role's; the owner has none; with no limit a person approves any amount. mayChange is true for an owner or admin who can approve expenses.", "operationId": "getApiExpensesApprovalLimits", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesApprovalLimitsResponse" }, "example": { "limits": [ { "id": "6f1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "roleId": "0b6f2a3c-7d4e-4f5a-9b8c-1d2e3f4a5b6c", "roleName": "Accountant", "maxAmount": 5000.0 } ], "mayChange": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Expenses & claims" ], "summary": "Set one role's or one person's approval limit (exactly one of roleId and userId); setting it again replaces it. An approval above the approver's limit is refused with 409, and a bill saved by somebody over their limit waits for an approver whose limit covers it. Owner or admin who can approve expenses; an approver may not set their own.", "operationId": "postApiExpensesApprovalLimits", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roleId": { "type": "string" }, "userId": { "type": "null" }, "maxAmount": { "type": "number" } } }, "example": { "roleId": "0b6f2a3c-7d4e-4f5a-9b8c-1d2e3f4a5b6c", "userId": null, "maxAmount": 5000.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesApprovalLimitsResponse" }, "example": { "limits": [ { "id": "6f1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "roleId": "0b6f2a3c-7d4e-4f5a-9b8c-1d2e3f4a5b6c", "roleName": "Accountant", "maxAmount": 5000.0 } ], "mayChange": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/approval-limits/{id}": { "delete": { "tags": [ "Expenses & claims" ], "summary": "Remove an approval limit; that role or person can approve any amount again. Owner or admin who can approve expenses.", "operationId": "deleteApiExpensesApprovalLimitsById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "limits": { "type": "array", "items": { "type": "object" } }, "mayChange": { "type": "boolean" } } }, "example": { "limits": [], "mayChange": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/approval-policy": { "get": { "tags": [ "Expenses & claims" ], "summary": "The amount from which an expense claim, mileage trip, per-diem claim or supplier bill needs a second approval from a different person.", "operationId": "getApiExpensesApprovalPolicy", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesApprovalPolicyResponse" }, "example": { "secondApprovalFrom": 1.0, "approvers": 1, "mayChange": false, "summary": "Consulting services — August 2026" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Expenses & claims" ], "summary": "Set the second-approval amount, or turn it off with null. The owner or an admin who can approve expenses; refused while fewer than two people can approve.", "operationId": "putApiExpensesApprovalPolicy", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiExpensesApprovalPolicyRequest" }, "example": { "secondApprovalFrom": 10000.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesApprovalPolicyResponse" }, "example": { "secondApprovalFrom": 1.0, "approvers": 1, "mayChange": false, "summary": "Consulting services — August 2026" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/payment-run": { "get": { "tags": [ "Expenses & claims" ], "summary": "What a supplier payment run would pay: approved, owed bills due by the date, the ones it cannot pay with the reason, and the total.", "operationId": "getApiBillsPaymentRun", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dueBy", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-10-10" }, { "name": "contactId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "payable": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBillsPaymentRunResponseBlockedItem" } }, "blocked": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBillsPaymentRunResponseBlockedItem" } }, "total": { "type": "number" }, "dueBy": { "type": "string" }, "fileNote": { "type": "string" } } }, "example": { "payable": [ { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendor": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billNumber": "INV-0001", "dueDate": "2026-09-01", "amount": 10005.0, "payee": "text", "blockedReason": "Budget deferred to the next financial year.", "warning": "text" } ], "blocked": [ { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendor": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billNumber": "INV-0001", "dueDate": "2026-09-01", "amount": 10005.0, "payee": "text", "blockedReason": "Budget deferred to the next financial year.", "warning": "text" } ], "total": 10005.0, "dueBy": "text", "fileNote": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/payment-runs": { "get": { "tags": [ "Expenses & claims" ], "summary": "The company's supplier payment runs, newest first.", "operationId": "getApiBillsPaymentRuns", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBillsPaymentRunsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "payDate": "2026-09-01", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountName": "Karoo Fresh Holdings Ltd", "total": 10005.0, "billCount": 3, "lines": [ { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendor": "Karoo Fresh Holdings Ltd", "billNumber": "INV-0001", "beneficiaryName": "Karoo Fresh Holdings Ltd", "payee": "text", "amount": 10005.0, "reference": "INV-0001" } ], "createdByName": "Thandi Mokoena", "createdAt": "2026-09-01T09:15:00Z", "fileName": "SignedPO-4417.pdf" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Expenses & claims" ], "summary": "Pay the chosen bills in one run from one bank account, each through the bill's own pay path. All or nothing; the same clientId twice pays nothing twice.", "operationId": "postApiBillsPaymentRuns", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "bankAccountId": { "type": "string" }, "billIds": { "type": "array", "items": { "type": "string" } } } }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsPaymentRunsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "payDate": "2026-09-01", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountName": "Karoo Fresh Holdings Ltd", "total": 10005.0, "billCount": 3, "lines": [ { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendor": "Karoo Fresh Holdings Ltd", "billNumber": "INV-0001", "beneficiaryName": "Karoo Fresh Holdings Ltd", "payee": "text", "amount": 10005.0, "reference": "INV-0001" } ], "createdByName": "Thandi Mokoena", "createdAt": "2026-09-01T09:15:00Z", "fileName": "SignedPO-4417.pdf" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/payment-runs/{id}": { "get": { "tags": [ "Expenses & claims" ], "summary": "One supplier payment run and the bills it paid.", "operationId": "getApiBillsPaymentRunsById", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsPaymentRunsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "payDate": "2026-09-01", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountName": "Karoo Fresh Holdings Ltd", "total": 10005.0, "billCount": 3, "lines": [ { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendor": "Karoo Fresh Holdings Ltd", "billNumber": "INV-0001", "beneficiaryName": "Highveld Provident Fund", "payee": "text", "amount": 10005.0, "reference": "INV-0001" } ], "createdByName": "Thandi Mokoena", "createdAt": "2026-09-01T09:15:00Z", "fileName": "SignedPO-4417.pdf" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/payment-runs/{id}/bank-file": { "get": { "tags": [ "Expenses & claims" ], "summary": "The run's bank payment file. Without ?bank= the schedule (CSV: beneficiary name, account number, branch code, amount, reference); ?bank=fnb, standard-bank or investec is that bank's own upload layout, or 422 with blockingIssues naming what to fix. Downloaded, never sent to a bank.", "operationId": "getApiBillsPaymentRunsByIdBankFile", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bank", "in": "query", "required": false, "schema": { "type": "string" }, "example": "fnb" } ], "responses": { "200": { "description": "A plain-text download.", "content": { "text/plain": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/claim-run": { "get": { "tags": [ "Expenses & claims" ], "summary": "What a claims run would pay now: every approved, unpaid expense, mileage and per-diem claim, each owed to an employee on the payroll, and those that cannot be paid in a run with the reason.", "operationId": "getApiExpensesClaimRun", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "payable": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiExpensesClaimRunResponseBlockedItem" } }, "blocked": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiExpensesClaimRunResponseBlockedItem" } }, "total": { "type": "number" }, "employeeCount": { "type": "integer" } } }, "example": { "payable": [ { "kind": "standard", "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "claimant": "text", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "amount": 10005.0, "status": "sent", "stage": "text", "receiptUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "blockedReason": "Budget deferred to the next financial year.", "runId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "blocked": [ { "kind": "standard", "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "claimant": "text", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "amount": 10005.0, "status": "sent", "stage": "text", "receiptUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "blockedReason": "Budget deferred to the next financial year.", "runId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "total": 10005.0, "employeeCount": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/claim-runs": { "get": { "tags": [ "Expenses & claims" ], "summary": "The company's claims runs, newest first.", "operationId": "getApiExpensesClaimRuns", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiExpensesClaimRunsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "payDate": "2026-09-01", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountName": "Karoo Fresh Holdings Ltd", "total": 10005.0, "claimCount": 3, "employeeCount": 3, "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Expenses & claims" ], "summary": "Pay the chosen staff claims in one run from one bank account, each through its own register's pay path. All or nothing; the same clientId twice pays nothing twice.", "operationId": "postApiExpensesClaimRuns", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "bankAccountId": { "type": "string" }, "claims": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" } } } } } }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "claims": [ { "kind": "expense", "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiExpensesClaimRunsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "payDate": "2026-09-01", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountName": "Karoo Fresh Holdings Ltd", "total": 10005.0, "claimCount": 3, "employeeCount": 3, "createdAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/claim-runs/{id}/bank-file": { "get": { "tags": [ "Expenses & claims" ], "summary": "The claims run's bank payment file, one line per employee. Without ?bank= the schedule; ?bank=fnb, standard-bank or investec is that bank's own upload layout, or 422 with blockingIssues naming what to fix. Downloaded, never sent to a bank.", "operationId": "getApiExpensesClaimRunsByIdBankFile", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bank", "in": "query", "required": false, "schema": { "type": "string" }, "example": "fnb" } ], "responses": { "200": { "description": "A plain-text download.", "content": { "text/plain": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/expenses/claims-report": { "get": { "tags": [ "Expenses & claims" ], "summary": "Staff claims by employee and stage (waiting, owed, paid, rejected), optionally dated ?from= and ?to= (yyyy-MM-dd), each with its receipt and the run that paid it. The owed total is what account 2120 holds for claims.", "operationId": "getApiExpensesClaimsReport", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-31" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiExpensesClaimRunResponseBlockedItem" } }, "byEmployee": { "type": "array", "items": { "type": "object", "properties": { "claimant": { "type": "string" }, "employeeId": { "type": "string" }, "count": { "type": "integer" }, "owed": { "type": "number" }, "paid": { "type": "number" } } } }, "waiting": { "type": "number" }, "owed": { "type": "number" }, "paid": { "type": "number" }, "rejected": { "type": "number" } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "claims": [ { "kind": "standard", "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "claimant": "text", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "amount": 10005.0, "status": "sent", "stage": "text", "receiptUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "blockedReason": "Budget deferred to the next financial year.", "runId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "byEmployee": [ { "claimant": "text", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "count": 3, "owed": 1.0, "paid": 1.0 } ], "waiting": 1.0, "owed": 1.0, "paid": 1.0, "rejected": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/suppliers/{id}/bank-details": { "get": { "tags": [ "Expenses & claims" ], "summary": "A supplier's bank details, which a payment run pays into.", "operationId": "getApiSuppliersByIdBankDetails", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSuppliersByIdBankDetailsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSuppliersByIdBankDetailsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Expenses & claims" ], "summary": "Set a supplier's bank details from their bank confirmation letter. Refused unless usable; the change is audited.", "operationId": "putApiSuppliersByIdBankDetails", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankName": { "type": "string" }, "accountNumber": { "type": "string" }, "branchCode": { "type": "string" }, "accountType": { "type": "string" } } }, "example": { "bankName": "FNB", "accountNumber": "62012345678", "branchCode": "250655", "accountType": "current" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSuppliersByIdBankDetailsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSuppliersByIdBankDetailsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/credit-notes": { "get": { "tags": [ "Expenses & claims" ], "summary": "Supplier credit notes, newest first, optionally only those against one bill. A credit note is carried as a bill of kind credit_note with negative figures, so the ageing, the VAT201 and the supplier statement are reduced by it.", "operationId": "getApiBillsCreditNotes", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" }, { "name": "billId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "8ed9dcd6-0243-510c-a938-da741440b9ce" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBillsCreditNotesResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "creditNoteNumber": "CN-0001", "issueDate": "2026-09-01", "creditedBillId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "creditedBillNumber": "CN-0001", "supplierName": "Karoo Fresh Holdings Ltd", "net": 8700.0, "vat": 1305.0, "total": 10005.0, "settlement": "text", "status": "sent", "reason": "Budget deferred to the next financial year.", "supplierReturnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "refundedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/{billId}/credit-notes": { "post": { "tags": [ "Expenses & claims" ], "summary": "Raise the supplier's credit note against a bill: DR 2110 / CR the line's account (5020 for stock) / CR 1340. Against a bill still owed it is taken off that bill's payment; against a bill already paid the supplier owes the money until their refund is recorded. Refused beyond what the bill billed, in total or per order line.", "operationId": "postApiBillsByBillIdCreditNotes", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "billId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "creditNoteNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "reason": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "vatRate": { "type": "number" }, "poLineId": { "type": "string" }, "category": { "type": "string" } } } }, "clientId": { "type": "string" } } }, "example": { "creditNoteNumber": "CN-4471", "issueDate": "2026-09-30", "reason": "Price agreed down", "lines": [ { "description": "Argon 20kg", "quantity": 2.0, "unitPrice": 400.0, "vatRate": 15.0, "poLineId": "72c5521b-e186-531f-b4bd-196251336e28", "category": "stock" } ], "clientId": "453b20f0-8fc1-50d0-9471-51761784522b" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBillsCreditNotesResponseItem" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBillsByBillIdCreditNotesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/credit-notes/{id}/refund": { "post": { "tags": [ "Expenses & claims" ], "summary": "Record the supplier's refund of a credit raised against a bill already paid: DR 1350 / CR 2110.", "operationId": "postApiBillsCreditNotesByIdRefund", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLedgerBooksOpenResponse" }, "example": { "date": "2026-09-30" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBillsCreditNotesResponseItem" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBillsByBillIdCreditNotesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/credit-notes/{id}/applicable-bills": { "get": { "tags": [ "Expenses & claims" ], "summary": "The bills a standing supplier credit can come off: its supplier's, owed, in its currency, each with what is left to pay.", "operationId": "getApiBillsCreditNotesByIdApplicableBills", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "payable": { "type": "number" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "INV-0001", "dueDate": "2026-09-01", "payable": 1.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/credit-notes/{id}/apply": { "post": { "tags": [ "Expenses & claims" ], "summary": "Apply a credit standing against no bill to the supplier's bill, whole or (a credit brought across at take-on) in part. Nothing posts: both are in 2110 already. It comes off that bill's payment, and a bill it covers whole is settled with no money moved.", "operationId": "postApiBillsCreditNotesByIdApply", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "billId": { "type": "string" }, "amount": { "type": "number" } } }, "example": { "billId": "8ed9dcd6-0243-510c-a938-da741440b9ce", "amount": 300.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "creditNoteNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "creditedBillId": { "type": "string" }, "creditedBillNumber": { "type": "string" }, "supplierName": { "type": "string" }, "net": { "type": "number" }, "vat": { "type": "number" }, "total": { "type": "number" }, "settlement": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": "string" }, "supplierReturnId": { "type": "string" }, "refundedAt": { "type": "string" }, "applied": { "type": "boolean" }, "openingBalance": { "type": "boolean" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "creditNoteNumber": "CN-0001", "issueDate": "2026-09-01", "creditedBillId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "creditedBillNumber": "CN-0001", "supplierName": "Karoo Fresh Holdings Ltd", "net": 8700.0, "vat": 1305.0, "total": 10005.0, "settlement": "text", "status": "due", "reason": "Budget deferred to the next financial year.", "supplierReturnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "refundedAt": "2026-09-01T09:15:00Z", "applied": false, "openingBalance": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/credit-notes/{id}/unapply": { "post": { "tags": [ "Expenses & claims" ], "summary": "Take an application back off its bill: the credit stands open again and the bill owes what it did. Refused while the bill stands paid.", "operationId": "postApiBillsCreditNotesByIdUnapply", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/credit-notes/{id}/void": { "post": { "tags": [ "Expenses & claims" ], "summary": "Void a credit note that has not been settled; its journal is reversed and the bill owes what it did before.", "operationId": "postApiBillsCreditNotesByIdVoid", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBillsCreditNotesResponseItem" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBillsByBillIdCreditNotesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "Purchase orders and the open commitment they represent.", "operationId": "getApiPurchaseOrders", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "includeClosed", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPurchaseOrdersResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPurchaseOrdersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/{id}": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "One order with its lines and receipt history.", "operationId": "getApiPurchaseOrdersById", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPurchaseOrdersByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPurchaseOrdersByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/{id}/approve": { "post": { "tags": [ "Purchasing & suppliers" ], "summary": "Approve an order for transmission.", "operationId": "postApiPurchaseOrdersByIdApprove", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPurchaseOrdersByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPurchaseOrdersByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/{id}/cancel": { "post": { "tags": [ "Purchasing & suppliers" ], "summary": "Cancel an order and release its commitment.", "operationId": "postApiPurchaseOrdersByIdCancel", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPurchaseOrdersByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPurchaseOrdersByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/{id}/revisions": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "Every earlier version of an order, newest first — what it said before each change made after it was approved or sent.", "operationId": "getApiPurchaseOrdersByIdRevisions", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "revision": { "type": "integer" }, "createdAt": { "type": "string" }, "changedByName": { "type": "string" }, "netBefore": { "type": "number" }, "netAfter": { "type": "number" }, "returnedForApproval": { "type": "boolean" }, "statusBefore": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" } } } } } } }, "example": [ { "revision": 0, "createdAt": "2026-09-01T10:15:00Z", "changedByName": "Thandi Nkosi", "netBefore": 8700.0, "netAfter": 11600.0, "returnedForApproval": true, "statusBefore": "approved", "lines": [ { "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0 } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/{id}/lines/{lineId}/match-basis": { "put": { "tags": [ "Purchasing & suppliers" ], "summary": "Whether an invoice for this order line needs a delivery behind it: true matches it to the order alone, false requires a receipt, null returns it to the default.", "operationId": "putApiPurchaseOrdersByIdLinesByLineIdMatchBasis", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "matchOnOrder": { "type": "boolean" } } }, "example": { "matchOnOrder": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "supplierName": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "expectedDate": { "type": "string", "format": "date" }, "status": { "type": "string" }, "total": { "type": "number" }, "outstandingValue": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string" }, "description": { "type": "string" }, "qtyOrdered": { "type": "number" }, "qtyReceived": { "type": "number" }, "qtyOutstanding": { "type": "number" }, "unitPrice": { "type": "number" }, "matchOnOrder": { "type": "boolean" }, "matchOnOrderSet": { "type": "boolean" } } } }, "receiptCount": { "type": "integer" }, "revision": { "type": "integer" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "PO-0001", "supplierName": "Karoo Fresh Holdings Ltd", "issueDate": "2026-09-01", "expectedDate": "2026-09-01", "status": "approved", "total": 10005.0, "outstandingValue": 10005.0, "lines": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyOrdered": 3.0, "qtyReceived": 0.0, "qtyOutstanding": 3.0, "unitPrice": 2900.0, "matchOnOrder": true, "matchOnOrderSet": true } ], "receiptCount": 0, "revision": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/{id}/receipts": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "What has been received against this order.", "operationId": "getApiPurchaseOrdersByIdReceipts", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPurchaseOrdersByIdReceiptsResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "receiptDate": "2026-09-01", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "deliveryNoteRef": "INV-0001", "notes": "Budget deferred to the next financial year.", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyReceived": 1.0, "unitCost": 2900.0, "lineTotal": 8700.0, "batchNumber": "INV-0001" } ], "total": 10005.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/{id}/receive": { "post": { "tags": [ "Purchasing & suppliers" ], "summary": "Receive goods. The stock movement is dated the RECEIPT date, not the day it was keyed — the journal already was, so a backdated capture used to put stock and the GL in different periods for one event.", "operationId": "postApiPurchaseOrdersByIdReceive", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "fxRate": { "type": "number" }, "receiptDate": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string" }, "qtyReceived": { "type": "number" }, "unitCost": { "type": "number" }, "batchNumber": { "type": "string" }, "expiryDate": { "type": "string", "format": "date" } } } }, "deliveryNoteRef": { "type": "string" }, "locationId": { "type": "string" }, "notes": { "type": "string" }, "createBill": { "type": "boolean" } } }, "example": { "clientId": "b8fb24bf-f65e-5730-8c45-a314ee0bb216", "fxRate": 18.5, "receiptDate": "2026-09-30", "lines": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyReceived": 2.0, "unitCost": 2900.0, "batchNumber": "INV-0001", "expiryDate": "2026-09-01" } ], "deliveryNoteRef": "INV-0001", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "createBill": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "receipt": { "$ref": "#/components/schemas/GetApiPurchaseOrdersByIdReceiptsResponseItem" }, "billId": { "type": "string" } } }, "example": { "receipt": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "receiptDate": "2026-09-01", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "deliveryNoteRef": "INV-0001", "notes": "Budget deferred to the next financial year.", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyReceived": 1.0, "unitCost": 2900.0, "lineTotal": 8700.0, "batchNumber": "INV-0001" } ], "total": 10005.0 }, "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/drop-ship": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "Drop-ship orders — for one sale, or every one still open. A drop-shipped line moves no stock: the supplier delivers to the customer, and their despatch is the cost of the sale.", "operationId": "getApiPurchaseOrdersDropShip", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "salesInvoiceId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "afc5d92b-ef69-5faf-9611-ed55708cd855" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPurchaseOrdersDropShipResponse" } } } }, "example": { "orders": [ { "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "status": "sent", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "salesInvoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "salesInvoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "deliveryAddress": "12 Long Street, Cape Town, 8001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0, "unitCost": 2900.0, "qtyDespatched": 1.0, "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Purchasing & suppliers" ], "summary": "Drop-ship one product line of a tax invoice: a draft order to the product's approved supplier, addressed to the customer. The sale stops taking those goods off the shelf; confirming the supplier's despatch (receive) raises their bill against cost of sales, never through inventory.", "operationId": "postApiPurchaseOrdersDropShip", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "supplierId": { "type": "string" }, "unitCost": { "type": "number" }, "salesInvoiceId": { "type": "string" }, "lineId": { "type": "string" }, "deliveryAddress": { "type": "string" } } }, "example": { "productId": "8f5dddde-b378-584b-8d66-7d9bc57fa970", "supplierId": "118cb679-0914-5f4a-a2e4-55b1ae1f3ab5", "unitCost": 400.0, "salesInvoiceId": "2ece2ebc-6815-58cc-88ec-bb446dc413d1", "lineId": "c0c15f3f-cb19-5207-a739-531ddb52a122", "deliveryAddress": "12 Church Street, Graaff-Reinet, 6280" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPurchaseOrdersDropShipResponse" }, "example": { "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "status": "sent", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "salesInvoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "salesInvoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "deliveryAddress": "12 Long Street, Cape Town, 8001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0, "unitCost": 2900.0, "qtyDespatched": 1.0, "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/landed-costs": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "Landed-cost dockets — freight, duty and clearing waiting to be apportioned into stock.", "operationId": "getApiLandedCosts", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLandedCostsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "docketNumber": "INV-0001", "docketDate": "2026-09-01", "description": "Consulting services — August 2026", "vesselOrWaybill": "text", "customsMrn": "text", "allocationMethod": "eft", "status": "sent", "totalCharges": 10005.0, "totalCapitalised": 10005.0, "totalExpensed": 10005.0, "totalRecoverable": 10005.0, "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "postedAt": "2026-09-01T09:15:00Z", "notes": "Budget deferred to the next financial year.", "charges": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "chargeType": "standard", "label": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 10005.0, "capitalise": true, "expenseAccountCode": "CT-001" } ], "receiptIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "receiptNumbers": [ "INV-0001" ], "allocations": [ { "goodsReceiptLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "goodsReceiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "description": "Consulting services — August 2026", "qty": 3.0, "invoiceUnitCost": 2900.0, "lineValue": 10005.0, "basisAmount": 10005.0, "allocatedAmount": 10005.0, "landedUnitCost": 2900.0, "unitCostBefore": 2900.0, "unitCostAfter": 2900.0, "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "batchNumber": "INV-0001", "capitalisable": true } ], "isPreview": true, "uncapitalised": 1.0, "warnings": [] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Purchasing & suppliers" ], "summary": "Open a docket against one or more goods receipts.", "operationId": "postApiLandedCosts", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLandedCostsRequest" }, "example": { "clientId": "4ea78728-ddfd-5b57-8fd4-e58dca8360d6", "docketNumber": "SHIP-2026-14", "docketDate": "2026-09-01", "description": "Consulting services — August 2026", "vesselOrWaybill": "MSC AURORA / MEDU1234567", "customsMrn": "26ZADUR00012345", "allocationMethod": "eft", "notes": "Budget deferred to the next financial year.", "charges": [ { "chargeType": "standard", "description": "Consulting services — August 2026", "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 18400.0, "capitalise": true, "expenseAccountCode": "CT-001" } ], "goodsReceiptIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLandedCostsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLandedCostsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/landed-costs/{id}": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "One docket and its apportionment.", "operationId": "getApiLandedCostsById", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLandedCostsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLandedCostsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Purchasing & suppliers" ], "summary": "Change a docket before it is posted.", "operationId": "putApiLandedCostsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLandedCostsRequest" }, "example": { "clientId": "bb866a9b-544a-5857-b5ef-3dc5e39b4fc7", "docketNumber": "INV-0001", "docketDate": "2026-09-01", "description": "Consulting services — August 2026", "vesselOrWaybill": "MSC AURORA / MEDU1234567", "customsMrn": "26ZADUR00012345", "allocationMethod": "eft", "notes": "Budget deferred to the next financial year.", "charges": [ { "chargeType": "standard", "description": "Consulting services — August 2026", "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 9200.0, "capitalise": true, "expenseAccountCode": "CT-001" } ], "goodsReceiptIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLandedCostsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLandedCostsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Purchasing & suppliers" ], "summary": "Discard an unposted docket.", "operationId": "deleteApiLandedCostsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/landed-costs/bill-options": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "Supplier invoices that can be linked to a landed-cost charge — live bills, newest first, by number or supplier.", "operationId": "getApiLandedCostsBillOptions", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "dcf" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "billId": { "type": "string" }, "billNumber": { "type": "string" }, "vendor": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" } } } }, "example": [ { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billNumber": "DCF-9001", "vendor": "Durban Clearing & Forwarding", "issueDate": "2026-10-12", "amount": 2300.0, "currency": "ZAR", "status": "due" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/landed-costs/{id}/charges/{chargeId}/bill": { "put": { "tags": [ "Purchasing & suppliers" ], "summary": "Link the agent's invoice to a charge (or unlink it with null), on a draft or a posted docket; a posted docket's accrual is then cleared by that bill.", "operationId": "putApiLandedCostsByIdChargesByChargeIdBill", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "chargeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "docketNumber": { "type": "string" }, "status": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "docketNumber": "SAD500-0001", "status": "posted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/landed-costs/{id}/post": { "post": { "tags": [ "Purchasing & suppliers" ], "summary": "Apportion the cost into the batches it brought in and raise the journal.", "operationId": "postApiLandedCostsByIdPost", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "docketId": { "type": "string" }, "status": { "type": "string" }, "journalId": { "type": "string" }, "totalCapitalised": { "type": "number" }, "totalExpensed": { "type": "number" }, "totalRecoverable": { "type": "number" }, "linesAdjusted": { "type": "integer" }, "batchesAdjusted": { "type": "integer" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLandedCostsResponseAllocationsItem" } }, "warnings": { "type": "array", "items": { "type": "object" } } } }, "example": { "docketId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "sent", "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "totalCapitalised": 10005.0, "totalExpensed": 10005.0, "totalRecoverable": 10005.0, "linesAdjusted": 1, "batchesAdjusted": 1, "allocations": [ { "goodsReceiptLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "goodsReceiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "description": "Consulting services — August 2026", "qty": 3.0, "invoiceUnitCost": 2900.0, "lineValue": 10005.0, "basisAmount": 10005.0, "allocatedAmount": 10005.0, "landedUnitCost": 2900.0, "unitCostBefore": 2900.0, "unitCostAfter": 2900.0, "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "batchNumber": "INV-0001", "capitalisable": true } ], "warnings": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/landed-costs/{id}/bill": { "post": { "tags": [ "Purchasing & suppliers" ], "summary": "Link the clearing agent's bill, keyed in Bills, to the docket's charges that name no bill yet, and re-post it: the bill then debits 2120 for what the docket accrued instead of expensing the same freight, duty and import VAT a second time. Refused for a bill in another currency or a docket with nothing left to link.", "operationId": "postApiLandedCostsByIdBill", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "billId": { "type": "string" } } }, "example": { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLandedCostsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLandedCostsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/landed-costs/defaults": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "Standing cost types and their apportionment basis.", "operationId": "getApiLandedCostsDefaults", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLandedCostsDefaultsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiLandedCostsDefaultsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Purchasing & suppliers" ], "summary": "Add a cost type.", "operationId": "postApiLandedCostsDefaults", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "supplierContactId": { "type": "string" }, "productId": { "type": "string" }, "chargeType": { "type": "string" }, "percentOfValue": { "type": "number" }, "capitalise": { "type": "boolean" }, "active": { "type": "boolean" }, "notes": { "type": "string" } } }, "example": { "clientId": "0a4f4aa1-b7dc-59cc-9cd4-fd01927b8fb9", "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "chargeType": "freight", "percentOfValue": 15.0, "capitalise": true, "active": true, "notes": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLandedCostsDefaultsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiLandedCostsDefaultsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/landed-costs/defaults/{id}": { "delete": { "tags": [ "Purchasing & suppliers" ], "summary": "Remove a cost type.", "operationId": "deleteApiLandedCostsDefaultsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/landed-costs/receipt-options": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "Goods receipts a docket can still be attached to.", "operationId": "getApiLandedCostsReceiptOptions", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "umhlanga" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "goodsReceiptId": { "type": "string" }, "receiptNumber": { "type": "string" }, "receiptDate": { "type": "string", "format": "date" }, "supplierName": { "type": "string" }, "deliveryNoteRef": { "type": "string" }, "lineCount": { "type": "integer" }, "totalValue": { "type": "number" }, "landedCostAlready": { "type": "number" } } } }, "example": [ { "goodsReceiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "receiptDate": "2026-09-01", "supplierName": "Karoo Fresh Holdings Ltd", "deliveryNoteRef": "INV-0001", "lineCount": 3, "totalValue": 10005.0, "landedCostAlready": 10005.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/suppliers/aged": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "Aged creditors by bucket.", "operationId": "getApiSuppliersAged", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSuppliersAgedResponseItem" } }, "example": [ { "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "asOf": "text", "lines": [ { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "total": 10005.0, "outstanding": 1.0, "daysOverdue": 30, "category": "Office supplies" } ], "totalOutstanding": 10005.0, "current": 1.0, "days30": 1.0, "days60": 1.0, "days90Plus": 1.0, "oldestDays": 30 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/suppliers/{id}/statement": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "A supplier statement as data.", "operationId": "getApiSuppliersByIdStatement", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSuppliersAgedResponseItem" }, "example": { "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "asOf": "text", "lines": [ { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "total": 10005.0, "outstanding": 1.0, "daysOverdue": 30, "category": "Office supplies" } ], "totalOutstanding": 10005.0, "current": 1.0, "days30": 1.0, "days60": 1.0, "days90Plus": 1.0, "oldestDays": 30 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/suppliers/{id}/statement.pdf": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "The same statement as a PDF.", "operationId": "getApiSuppliersByIdStatement.pdf", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/suppliers/{id}/send-statement": { "post": { "tags": [ "Purchasing & suppliers" ], "summary": "Send a remittance or statement to the supplier.", "operationId": "postApiSuppliersByIdSendStatement", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string" }, "message": { "type": "string" } } }, "example": { "channel": "email", "message": "Saved." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "channel": { "type": "string" }, "error": { "type": "string" } } }, "example": { "delivered": true, "channel": "email", "error": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/suppliers/{id}/reconcile": { "post": { "tags": [ "Purchasing & suppliers" ], "summary": "Reconcile the supplier's own statement against what Ledgr holds, and report the differences.", "operationId": "postApiSuppliersByIdReconcile", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplierBalance": { "type": "number" }, "asOf": { "type": "string", "format": "date" }, "supplierStatementDate": { "type": "string", "format": "date" } } }, "example": { "supplierBalance": 1500.0, "asOf": "2026-09-30", "supplierStatementDate": "2026-09-01" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "asOf": { "type": "string" }, "ourBalance": { "type": "number" }, "theirBalance": { "type": "number" }, "difference": { "type": "number" }, "agreed": { "type": "boolean" }, "openItems": { "type": "array", "items": { "type": "object", "properties": { "reference": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "outstanding": { "type": "number" }, "daysOverdue": { "type": "integer" }, "raisedAfterTheirStatement": { "type": "boolean" } } } }, "itemsRaisedAfterTheirStatement": { "type": "integer" }, "valueRaisedAfterTheirStatement": { "type": "number" } } }, "example": { "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "asOf": "text", "ourBalance": 10005.0, "theirBalance": 10005.0, "difference": 1.0, "agreed": true, "openItems": [ { "reference": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "outstanding": 1.0, "daysOverdue": 30, "raisedAfterTheirStatement": false } ], "itemsRaisedAfterTheirStatement": 1, "valueRaisedAfterTheirStatement": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/receipts/recent": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "The deliveries booked lately, newest first, with whether anything on each can still go back to the supplier and whether any of it is held for inspection. Bounded.", "operationId": "getApiPurchaseOrdersReceiptsRecent", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "receiptNumber": { "type": "string" }, "receiptDate": { "type": "string", "format": "date" }, "purchaseOrderId": { "type": "string" }, "purchaseOrderNumber": { "type": "string" }, "supplierName": { "type": "string" }, "total": { "type": "number" }, "billId": { "type": "string" }, "canReturn": { "type": "boolean" }, "awaitingInspection": { "type": "boolean" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "receiptDate": "2026-09-01", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "supplierName": "Karoo Fresh Holdings Ltd", "total": 10005.0, "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "canReturn": true, "awaitingInspection": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/receipts/{receiptId}": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "One delivery with everything that has happened to it since: per line what can still go back, what is held for inspection, what was rejected and not yet returned, and the returns already booked.", "operationId": "getApiPurchaseOrdersReceiptsByReceiptId", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "receiptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPurchaseOrdersReceiptsByReceiptIdResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "receiptDate": "2026-09-01", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "deliveryNoteRef": "INV-0001", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billNumber": "INV-0001", "billStatus": "sent", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyReceived": 1.0, "unitCost": 2900.0, "batchNumber": "INV-0001", "expiryDate": "2026-09-01", "qtyReturned": 1.0, "returnable": 1.0, "inspectionStatus": "sent", "qtyAccepted": 1.0, "qtyRejected": 1.0, "rejectionReason": "Budget deferred to the next financial year.", "awaitingInspection": 1.0, "rejectedNotReturned": 1.0, "qtyPrecision": 3, "vatRate": 15.0 } ], "returns": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "returnNumber": "INV-0001", "returnDate": "2026-09-01", "receiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "supplierName": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year.", "resolution": "text", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0, "unitCost": 2900.0, "creditValue": 10005.0, "stockValue": 10005.0 } ], "creditNoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "creditNoteNumber": "CN-0001", "creditTotal": 10005.0, "notice": "This run includes a catch-up deduction; the year-to-date total is correct." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/receipts/{receiptId}/returns": { "post": { "tags": [ "Purchasing & suppliers" ], "summary": "Send goods back to the supplier. Each line is drawn from the batch it came in on, at that batch's own cost (DR 5020 / CR 1310, any landed cost the supplier does not refund to 5070), and — where the delivery is billed — the supplier's credit note is raised against that bill in the same step. Refused if the goods are no longer in that batch.", "operationId": "postApiPurchaseOrdersReceiptsByReceiptIdReturns", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "receiptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string" }, "returnDate": { "type": "string", "format": "date" }, "reason": { "type": "string" }, "resolution": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "receiptLineId": { "type": "string" }, "qty": { "type": "number" } } } }, "raiseCreditNote": { "type": "boolean" }, "creditNoteNumber": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "notes": "Two cylinders leaking at the valve", "returnDate": "2026-09-30", "reason": "Damaged on arrival", "resolution": "credit", "lines": [ { "receiptLineId": "e02873ce-3aa1-51c4-9e5b-e894da93d666", "qty": 2.0 } ], "raiseCreditNote": true, "creditNoteNumber": "CN-4471", "clientId": "7f9a9036-aa16-5e27-b15d-e22b36a84861" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPurchaseOrdersReturnsResponseItem" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "returnNumber": "INV-0001", "returnDate": "2026-09-01", "receiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "supplierName": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year.", "resolution": "text", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0, "unitCost": 2900.0, "creditValue": 10005.0, "stockValue": 10005.0 } ], "creditNoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "creditNoteNumber": "CN-0001", "creditTotal": 10005.0, "notice": "This run includes a catch-up deduction; the year-to-date total is correct." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/receipts/{receiptId}/inspection": { "post": { "tags": [ "Purchasing & suppliers" ], "summary": "Record an inspection of goods held on receipt: accepted units are released to stock, rejected ones stay held until they go back. Accepted and rejected must account for every held unit, and a rejection needs a reason. `returnRejected` books the return (and its credit note) in the same step.", "operationId": "postApiPurchaseOrdersReceiptsByReceiptIdInspection", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "receiptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "receiptLineId": { "type": "string" }, "qtyAccepted": { "type": "number" }, "qtyRejected": { "type": "number" }, "reason": { "type": "string" } } } }, "returnRejected": { "type": "boolean" }, "returnDate": { "type": "string", "format": "date" } } }, "example": { "lines": [ { "receiptLineId": "9ee0b73c-c65d-5cbc-bbe2-0c3b98b97078", "qtyAccepted": 8.0, "qtyRejected": 2.0, "reason": "Leaking valve" } ], "returnRejected": true, "returnDate": "2026-09-30" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "receipt": { "$ref": "#/components/schemas/GetApiPurchaseOrdersReceiptsByReceiptIdResponse" }, "released": { "type": "number" }, "rejected": { "type": "number" }, "supplierReturn": { "$ref": "#/components/schemas/GetApiPurchaseOrdersReturnsResponseItem" } } }, "example": { "receipt": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "receiptDate": "2026-09-01", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "deliveryNoteRef": "INV-0001", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billNumber": "INV-0001", "billStatus": "sent", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyReceived": 1.0, "unitCost": 2900.0, "batchNumber": "INV-0001", "expiryDate": "2026-09-01", "qtyReturned": 1.0, "returnable": 1.0, "inspectionStatus": "sent", "qtyAccepted": 1.0, "qtyRejected": 1.0, "rejectionReason": "Budget deferred to the next financial year.", "awaitingInspection": 1.0, "rejectedNotReturned": 1.0, "qtyPrecision": 3, "vatRate": 15.0 } ], "returns": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "returnNumber": "INV-0001", "returnDate": "2026-09-01", "receiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "supplierName": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year.", "resolution": "text", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0, "unitCost": 2900.0, "creditValue": 10005.0, "stockValue": 10005.0 } ], "creditNoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "creditNoteNumber": "CN-0001", "creditTotal": 10005.0, "notice": "This run includes a catch-up deduction; the year-to-date total is correct." } ] }, "released": 1.0, "rejected": 1.0, "supplierReturn": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "returnNumber": "INV-0001", "returnDate": "2026-09-01", "receiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "supplierName": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year.", "resolution": "text", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0, "unitCost": 2900.0, "creditValue": 10005.0, "stockValue": 10005.0 } ], "creditNoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "creditNoteNumber": "CN-0001", "creditTotal": 10005.0, "notice": "This run includes a catch-up deduction; the year-to-date total is correct." } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/inspection-queue": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "Every delivered line held for inspection, oldest first — valued and in stock, but not available to sell, issue or build with until inspected.", "operationId": "getApiPurchaseOrdersInspectionQueue", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "receiptId": { "type": "string" }, "receiptNumber": { "type": "string" }, "receiptDate": { "type": "string", "format": "date" }, "purchaseOrderNumber": { "type": "string" }, "supplierName": { "type": "string" }, "receiptLineId": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "awaiting": { "type": "number" }, "unitCost": { "type": "number" }, "qtyPrecision": { "type": "integer" }, "batchNumber": { "type": "string" } } } }, "example": [ { "receiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "receiptDate": "2026-09-01", "purchaseOrderNumber": "PO-0001", "supplierName": "Karoo Fresh Holdings Ltd", "receiptLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "awaiting": 1.0, "unitCost": 2900.0, "qtyPrecision": 3, "batchNumber": "INV-0001" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/inspection/products": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "The products whose deliveries are held for inspection on receipt.", "operationId": "getApiPurchaseOrdersInspectionProducts", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPurchaseOrdersInspectionProductsResponseItem" } }, "example": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "inspectOnReceipt": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/inspection/products/{productId}": { "put": { "tags": [ "Purchasing & suppliers" ], "summary": "Turn inspect-on-receipt on or off for a product. Needs inventory:edit — it is a fact about the goods.", "operationId": "putApiPurchaseOrdersInspectionProductsByProductId", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inspectOnReceipt": { "type": "boolean" } } }, "example": { "inspectOnReceipt": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPurchaseOrdersInspectionProductsResponseItem" }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "inspectOnReceipt": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/returns": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "Returns to supplier, newest first, with the credit note each raised. Bounded.", "operationId": "getApiPurchaseOrdersReturns", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPurchaseOrdersReturnsResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "returnNumber": "INV-0001", "returnDate": "2026-09-01", "receiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "INV-0001", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "supplierName": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year.", "resolution": "text", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0, "unitCost": 2900.0, "creditValue": 10005.0, "stockValue": 10005.0 } ], "creditNoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "creditNoteNumber": "CN-0001", "creditTotal": 10005.0, "notice": "This run includes a catch-up deduction; the year-to-date total is correct." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/purchase-orders/{id}/scan": { "get": { "tags": [ "Purchasing & suppliers" ], "summary": "What a scanned or typed code is against this order: the product it names (barcode first, then SKU), whether it is on the order, and whether to ask for a batch number and expiry. A product not on the order is named in the refusal.", "operationId": "getApiPurchaseOrdersByIdScan", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" }, "example": "6001234567890" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "onOrder": { "type": "boolean" }, "asksForBatch": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "code": "CT-001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "onOrder": true, "asksForBatch": true, "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-feeds": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "This company's Investec feeds, plus whether a feed can be connected at all and how to get the keys.", "operationId": "getApiBankFeeds", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "feeds": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBankFeedsResponseFeedsItem" } }, "availability": { "type": "object", "properties": { "secretStorageReady": { "type": "boolean" }, "secretStorageHint": { "type": "string" }, "developerPortalUrl": { "type": "string" }, "requiredFields": { "type": "array", "items": { "type": "string" } }, "instructions": { "type": "array", "items": { "type": "string" } } } }, "activeCount": { "type": "integer" }, "attentionCount": { "type": "integer" } } }, "example": { "feeds": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountName": "Karoo Fresh Holdings Ltd", "investecAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "investecAccountName": "Karoo Fresh Holdings Ltd", "investecAccountMasked": "text", "currency": "ZAR", "status": "active", "statusLabel": "Karoo Fresh Holdings Ltd", "lastSyncAt": "2026-09-01T09:15:00Z", "lastSyncStatus": "sent", "lastError": "text", "syncCount": 3, "totalImported": 1, "consecutiveFailures": 1, "nextAttemptAt": "2026-09-01T09:15:00Z", "syncFrom": "2026-09-01", "createdAt": "2026-09-01T09:15:00Z", "needsAttention": false, "attentionReason": "Budget deferred to the next financial year." } ], "availability": { "secretStorageReady": true, "secretStorageHint": "text", "developerPortalUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "requiredFields": [ "text" ], "instructions": [ "text" ] }, "activeCount": 3, "attentionCount": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Banking & reconciliation" ], "summary": "Connect a feed with your own Investec client id, secret and API key. They are proved against Investec before they are stored, and the reply carries the accounts they can see.", "operationId": "postApiBankFeeds", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "apiKey": { "type": "string" }, "syncFrom": { "type": "string", "format": "date" } } }, "example": { "clientId": "", "clientSecret": "", "apiKey": "", "syncFrom": "2026-06-01" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "feedId": { "type": "string" }, "status": { "type": "string" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBankFeedsResponseAccountsItem" } }, "message": { "type": "string" } } }, "example": { "feedId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "active", "accounts": [ { "investecAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "masked": "text", "currency": "ZAR", "linkedBankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "suggestedBankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-feeds/{id}/accounts": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "Re-read the Investec account list, with a suggested Ledgr account matched by account number.", "operationId": "getApiBankFeedsByIdAccounts", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBankFeedsResponseAccountsItem" } }, "example": [ { "investecAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "masked": "text", "currency": "ZAR", "linkedBankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "suggestedBankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-feeds/{id}/link": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Map an Investec account onto a Ledgr bank account. An unmapped feed imports nothing rather than guessing.", "operationId": "postApiBankFeedsByIdLink", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "investecAccountId": { "type": "string" }, "bankAccountId": { "type": "string" } } }, "example": { "investecAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBankFeedsResponseFeedsItem" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountName": "Karoo Fresh Holdings Ltd", "investecAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "investecAccountName": "Karoo Fresh Holdings Ltd", "investecAccountMasked": "text", "currency": "ZAR", "status": "active", "statusLabel": "Karoo Fresh Holdings Ltd", "lastSyncAt": "2026-09-01T09:15:00Z", "lastSyncStatus": "sent", "lastError": "text", "syncCount": 3, "totalImported": 1, "consecutiveFailures": 1, "nextAttemptAt": "2026-09-01T09:15:00Z", "syncFrom": "2026-09-01", "createdAt": "2026-09-01T09:15:00Z", "needsAttention": false, "attentionReason": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-feeds/{id}/sync": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Pull now. Idempotent — Investec's own transaction id plus a content signature, so nothing imports twice.", "operationId": "postApiBankFeedsByIdSync", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "feedId": { "type": "string" }, "status": { "type": "string" }, "fetched": { "type": "integer" }, "imported": { "type": "integer" }, "duplicates": { "type": "integer" }, "rejected": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "feedId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "active", "fetched": 1, "imported": 1, "duplicates": 1, "rejected": 0, "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-feeds/{id}/runs": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "The sync history, newest first. A feed that silently stops is worse than no feed.", "operationId": "getApiBankFeedsByIdRuns", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "feedId": { "type": "string" }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "trigger": { "type": "string" }, "status": { "type": "string" }, "startedAt": { "type": "string" }, "finishedAt": { "type": "string" }, "fetched": { "type": "integer" }, "imported": { "type": "integer" }, "duplicates": { "type": "integer" }, "rejected": { "type": "integer" }, "error": { "type": "string" } } } } } }, "example": { "feedId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "runs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "trigger": "text", "status": "active", "startedAt": "2026-09-01T09:15:00Z", "finishedAt": "2026-09-01T09:15:00Z", "fetched": 1, "imported": 1, "duplicates": 1, "rejected": 0, "error": "text" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-feeds/{id}": { "delete": { "tags": [ "Banking & reconciliation" ], "summary": "Disconnect and erase the stored Investec keys. Transactions already imported are kept.", "operationId": "deleteApiBankFeedsById", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "ok": true, "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-accounts": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "Bank accounts with balances and sparkline trends.", "operationId": "getApiBankAccounts", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "includeClosed", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBankAccountsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "accountNumber": "62012345678", "bankName": "FNB", "currency": "ZAR", "currentBalance": 10005.0, "statementBalance": 10005.0, "type": "standard", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Banking & reconciliation" ], "summary": "Add an account. Nine SA banks are supported for import. Send your own clientId (a UUID) and a retry after a lost response returns the account the first request added instead of adding it twice.", "operationId": "postApiBankAccounts", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" }, "currency": { "type": "string" }, "currentBalance": { "type": "number" }, "type": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "name": "Karoo Fresh Holdings Ltd", "accountNumber": "62811234567", "bankName": "FNB", "currency": "ZAR", "currentBalance": 10005.0, "type": "cheque", "clientId": "8b2f0c4e-1d7a-4e3b-9c55-6a0f2e7d1b94" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankAccountsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankAccountsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-accounts/unattributed": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "What the books hold on the bank control that no account claims: payments posted without naming the account they went into. Banking adds it to the accounts' total in the books.", "operationId": "getApiBankAccountsUnattributed", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" } } }, "example": { "amount": 930802.31 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-accounts/{id}": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "One account.", "operationId": "getApiBankAccountsById", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" }, "currency": { "type": "string" }, "statementBalance": { "type": "number" }, "currentBalance": { "type": "number" }, "type": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "accountNumber": "62012345678", "bankName": "FNB", "currency": "ZAR", "statementBalance": 10005.0, "currentBalance": 10005.0, "type": "standard", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Banking & reconciliation" ], "summary": "Update an account.", "operationId": "putApiBankAccountsById", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "statementCadenceDays": { "type": "integer" }, "name": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" }, "currentBalance": { "type": "number" }, "type": { "type": "string" }, "currency": { "type": "string" } } }, "example": { "statementCadenceDays": 31, "name": "FNB Business Cheque (main)", "accountNumber": "62012345678", "bankName": "FNB", "currentBalance": 10005.0, "type": "standard", "currency": "ZAR" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankAccountsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankAccountsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Banking & reconciliation" ], "summary": "Remove an account.", "operationId": "deleteApiBankAccountsById", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-accounts/{id}/close": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Close an account the business no longer uses. Its transactions and reconciliations stay readable; it leaves the account lists and the cash position and takes no new lines. Refused while a reconciliation is open, a bank feed is connected, or a line is dated after the closing date.", "operationId": "postApiBankAccountsByIdClose", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "closedOn": { "type": "string", "format": "date" } } }, "example": { "closedOn": "2026-08-31" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" }, "currency": { "type": "string" }, "currentBalance": { "type": "number" }, "statementBalance": { "type": "number" }, "type": { "type": "string" }, "closedOn": { "type": "string", "format": "date" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "accountNumber": "62012345678", "bankName": "FNB", "currency": "ZAR", "currentBalance": 10005.0, "statementBalance": 10005.0, "type": "standard", "closedOn": "2026-08-31", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-accounts/{id}/reopen": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Reopen a closed account, exactly as it was.", "operationId": "postApiBankAccountsByIdReopen", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" }, "currency": { "type": "string" }, "currentBalance": { "type": "number" }, "statementBalance": { "type": "number" }, "type": { "type": "string" }, "closedOn": { "type": "null" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "accountNumber": "62012345678", "bankName": "FNB", "currency": "ZAR", "currentBalance": 10005.0, "statementBalance": 10005.0, "type": "standard", "closedOn": null, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "Transactions for an account.", "operationId": "getApiBankTransactions", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "unmatched" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBankTransactionsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "reference": "INV-0001", "type": "standard", "status": "UNRECONCILED", "matchedInvoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "matchedExpenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "category": "Office supplies", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "source": "referral", "autoCreatedKind": "standard", "autoCreatedId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Banking & reconciliation" ], "summary": "Key a transaction by hand.", "operationId": "postApiBankTransactions", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankAccountId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "reference": { "type": "string" }, "type": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-08-14", "description": "PAYFAST ACME", "amount": 51750.0, "reference": "INV-0001", "type": "CREDIT", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankTransactionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankTransactionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/{id}": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "One transaction and its match state.", "operationId": "getApiBankTransactionsById", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "bankAccountId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "reference": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "matchedInvoiceId": { "type": "string" }, "matchedExpenseId": { "type": "string" }, "category": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "source": { "type": "string" }, "autoCreatedId": { "type": "string" }, "autoCreatedKind": { "type": "string" }, "ledgerNotice": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "reference": "INV-0001", "type": "standard", "status": "UNRECONCILED", "matchedInvoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "matchedExpenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "category": "Office supplies", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "source": "referral", "autoCreatedId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "autoCreatedKind": "standard", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Banking & reconciliation" ], "summary": "Delete a transaction.", "operationId": "deleteApiBankTransactionsById", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/import": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Import transactions already parsed into Ledgr's shape. TransactionDedupe matches a hand-keyed row against an uploaded one.", "operationId": "postApiBankTransactionsImport", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "dateCol", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" }, { "name": "descCol", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" }, { "name": "amountCol", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" }, { "name": "debitCol", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" }, { "name": "creditCol", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" }, { "name": "refCol", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" }, { "name": "hasHeader", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" }, { "name": "delimiter", "in": "query", "required": false, "schema": { "type": "string" }, "example": "tab" }, { "name": "filename", "in": "query", "required": false, "description": "The name to give the downloaded file.", "schema": { "type": "string" }, "example": "fnb-cheque-september.tsv" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankAccountId": { "type": "string" }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" } } } } } }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "transactions": [ { "date": "2026-08-14", "description": "PAYFAST ACME", "amount": 51750.0 } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "integer" }, "duplicates": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object" } } } }, "example": { "imported": 1, "duplicates": 1, "errors": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/{id}/match": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Match a transaction to an invoice or a bill. Money in settles an invoice; money out matched to an issued credit note records the customer's refund against it, and unmatching takes the refund back out. Money in is never matched to a credit note. Money out matched to a bill pays what the line moved: a line for all that the bill still owes settles it, a line for less is a part payment on it (the bill stays due, owing the rest), a line for more is refused (409); unmatching takes a part payment back off the bill.", "operationId": "postApiBankTransactionsByIdMatch", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "expenseId": { "type": "string" }, "billId": { "type": "string" }, "payrollPeriodId": { "type": "string" }, "category": { "type": "string" }, "createExpense": { "type": "boolean" }, "vatRate": { "type": "number" } } }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "expenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "payrollPeriodId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "category": "Office supplies", "createExpense": false, "vatRate": 15.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankTransactionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankTransactionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/{id}/unmatch": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Break a match.", "operationId": "postApiBankTransactionsByIdUnmatch", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankTransactionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankTransactionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reconciliation/{id}/report": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "One reconciliation as a report: cleared items, the items the bank has not shown yet, and the tie to the books.", "operationId": "getApiReconciliationByIdReport", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "accountName": { "type": "string" }, "ledgerCode": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "status": { "type": "string" }, "statementOpening": { "type": "number" }, "statementClosing": { "type": "number" }, "cleared": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReconciliationByIdReportResponseClearedItem" } }, "unclearedOut": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReconciliationByIdReportResponseClearedItem" } }, "unclearedIn": { "type": "array", "items": { "type": "object" } }, "bookBalance": { "type": "number" }, "currency": { "type": "string" }, "notInBooks": { "type": "array", "items": { "type": "object" } }, "notInBooksTotal": { "type": "number" }, "clearedTotal": { "type": "number" }, "unclearedOutTotal": { "type": "number" }, "unclearedInTotal": { "type": "number" }, "tie": { "type": "object", "properties": { "expectedBookBalance": { "type": "number" }, "bookBalance": { "type": "number" }, "difference": { "type": "number" }, "ties": { "type": "boolean" }, "sentence": { "type": "string" } } } } }, "example": { "sessionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountName": "FNB Business Cheque", "ledgerCode": "1350-01", "from": "2026-09-01", "to": "2026-09-30", "status": "FINALISED", "statementOpening": 0.0, "statementClosing": 4000.0, "cleared": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-07", "description": "INTERNET DEBIT ORDER", "reference": null, "amount": -1000.0, "matchedTo": "6240 Telephone & Internet" } ], "unclearedOut": [ { "id": "8c2d5e41-77b9-4a30-8e15-9f6b1d2c4a07", "date": "2026-09-28", "description": "CHEQUE 4471 SUPPLIER", "reference": null, "amount": -300.0, "matchedTo": "6180 Repairs & Maintenance" } ], "unclearedIn": [], "bookBalance": 3700.0, "currency": "ZAR", "notInBooks": [], "notInBooksTotal": 0.0, "clearedTotal": 4000.0, "unclearedOutTotal": -300.0, "unclearedInTotal": 0.0, "tie": { "expectedBookBalance": 3700.0, "bookBalance": 3700.0, "difference": 0.0, "ties": true, "sentence": "The books agree with the statement once the uncleared items are allowed for." } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/{id}/transfer-candidates": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "The lines that could be the other side of this one.", "operationId": "getApiBankTransactionsByIdTransferCandidates", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "bankAccountId": { "type": "string" }, "bankAccountName": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "type": { "type": "string" }, "daysApart": { "type": "integer" }, "why": { "type": "string" } } } }, "refusal": { "type": "null" }, "note": { "type": "null" }, "transfer": { "type": "null" }, "awaitingTransfers": { "type": "array", "items": { "type": "object" } } } }, "example": { "candidates": [ { "id": "8c2d5e41-77b9-4a30-8e15-9f6b1d2c4a07", "bankAccountId": "8c2d5e41-77b9-4a30-8e15-9f6b1d2c4a07", "bankAccountName": "Standard Bank Business Savings", "date": "2026-09-14", "description": "TRANSFER FROM CHEQUE", "amount": 5000.0, "currency": "ZAR", "type": "CREDIT", "daysApart": 0, "why": "The same figure, the other way, on the same day." } ], "refusal": null, "note": null, "transfer": null, "awaitingTransfers": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transfers": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Record a transfer between two of the tenant's own bank accounts.", "operationId": "postApiBankTransfers", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "outLineId": { "type": "string" }, "inLineId": { "type": "string" }, "fromBankAccountId": { "type": "string" }, "toBankAccountId": { "type": "string" } } }, "example": { "id": "e8b1c4d7-6a29-4f3e-9c05-1d7a8b2e4f63", "outLineId": "6f3c2a91-4d7e-4b08-9a15-3c8e2f7d1b40", "inLineId": "b27e9d04-1c6a-4e3f-8d52-9a0c7e4f6b13", "fromBankAccountId": "4e8a1c73-9b2d-4f65-a0e7-5d3b8c1f2a96", "toBankAccountId": "c93f5e28-7a14-4d0b-b6e9-2f8a0d4c7e51" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankTransfersResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankTransfersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transfers/{id}/complete": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Attach the second side to a transfer recorded from one line.", "operationId": "postApiBankTransfersByIdComplete", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lineId": { "type": "string" } } }, "example": { "lineId": "2a7d4f19-8e3c-4b60-9d1a-6c5e0f8b3a27" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankTransfersResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankTransfersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transfers/{id}": { "delete": { "tags": [ "Banking & reconciliation" ], "summary": "Take a recorded transfer back — one reversal, both lines freed.", "operationId": "deleteApiBankTransfersById", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiBillsByIdResponse" }, "example": { "ledgerNotice": "The reversal is dated 1 Oct 2026, because September is closed." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/card-receipts-in-transit": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "Card payments a gateway still holds: paid by link, waiting in 1366 Card Payments in Transit until the payout line settles them. A row with refund:true is a refund an online store gave its buyer and keeps back from its payout: it comes OFF the payout, and the settle names it as cardRefundId rather than cardReceiptId.", "operationId": "getApiBankTransactionsCardReceiptsInTransit", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "customerName": { "type": "string" }, "gateway": { "type": "string" }, "paidOn": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "refund": { "type": "boolean" } } } }, "example": [ { "id": "9b2d4e61-7a3c-4f08-b5e2-6c1a8d3f0e94", "invoiceId": "d15b8e42-3f9a-4c07-8e26-1b7d9a0c5f38", "invoiceNumber": "INV-2026-001", "customerName": "Umhlanga Florist", "gateway": "YOCO", "paidOn": "2026-10-05", "amount": 1150.0, "refund": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/driver-cash-banked": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "Drivers' cash the office banked that no statement line has matched yet: the deposit line settles it, posting nothing, because banking it already put it in the bank.", "operationId": "getApiBankTransactionsDriverCashBanked", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "driverName": { "type": "string" }, "bankAccountId": { "type": "string" }, "bankAccountName": { "type": "string" }, "bankedOn": { "type": "string", "format": "date" }, "reference": { "type": "string" }, "amount": { "type": "number" } } } }, "example": [ { "id": "4c8e2a17-9d3b-4f61-a0e5-7b2c9d1e3f48", "driverName": "Sipho Driver", "bankAccountId": "0a7d3e92-5b1c-4e86-9f24-3c8b6a1d7e05", "bankAccountName": "FNB Business Cheque", "bankedOn": "2026-10-08", "reference": "Deposit slip 0042", "amount": 1000.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/{id}/settle": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Settle several documents from one line, with an optional adjustment for the difference. On a store's payout a part may be a refund the store kept back (cardRefundId): it comes off the line, so the card receipts less the refunds less the fee on the adjustment are the line.", "operationId": "postApiBankTransactionsByIdSettle", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "amount": { "type": "number" } } } }, "adjustment": { "type": "object", "properties": { "accountCode": { "type": "string" }, "amount": { "type": "number" }, "description": { "type": "string" } } } } }, "example": { "allocations": [ { "invoiceId": "d15b8e42-3f9a-4c07-8e26-1b7d9a0c5f38", "amount": 1150.0 }, { "invoiceId": "7c0e3a56-2b8f-4d91-a4c3-8e6f1d2b9a07", "amount": 2300.0 } ], "adjustment": { "accountCode": "6030", "amount": -4.5, "description": "Bank charge on receipt" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "settled": { "type": "array", "items": { "type": "string" } }, "ledgerNotice": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "settled": [ "INV-2026-001", "INV-2026-002" ], "ledgerNotice": "R 3 450.00 settled 2 documents." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/{id}/on-behalf": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Book a money-out line as paid on behalf of another company of the group: this company's bank and an intercompany receivable, the other company's expense and an intercompany payable, and the register row — in one transaction. Unmatch takes all of it back out.", "operationId": "postApiBankTransactionsByIdOnBehalf", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string" }, "accountCode": { "type": "string" }, "vatRatePercent": { "type": "number" }, "description": { "type": "string" }, "contactId": { "type": "string" } } }, "example": { "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountCode": "6090", "vatRatePercent": 15.0, "description": "Municipal rates, Erf 1201", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankTransactionsByIdCodeResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "category": "Office supplies", "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/{id}/code": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Post a bank line to an account, or split it across several. Refused (400) for 2110, 1320, 1360, 1310, 1315 and 2115: each is the total of a register or a list, so a line is matched to the bill or invoice, recorded as a petty cash float or posted as stock, never coded straight to it. Money out coded to 5020 Purchases can name productId and quantity on a part: it clears those goods from 2115 Goods Received Not Invoiced (one line at a time, not in a bulk coding).", "operationId": "postApiBankTransactionsByIdCode", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "splits": { "type": "array", "items": { "type": "object", "properties": { "accountCode": { "type": "string" }, "vatRatePercent": { "type": "number" }, "amount": { "type": "number" }, "percent": { "type": "number" } } } }, "memo": { "type": "string" }, "contactId": { "type": "string" } } }, "example": { "splits": [ { "accountCode": "6120", "vatRatePercent": 15.0, "amount": 1380.0 }, { "accountCode": "6150", "vatRatePercent": 0.0, "percent": 40.0 } ], "memo": "Bank charges and the branch's share", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankTransactionsByIdCodeResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "category": "6120 Bank Charges", "ledgerNotice": "R 1 380.00 posted to 6120 Bank Charges." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/code": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Code several lines to the same account in one act. All or nothing.", "operationId": "postApiBankTransactionsCode", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "splits": { "type": "array", "items": { "type": "object", "properties": { "accountCode": { "type": "string" }, "vatRatePercent": { "type": "number" }, "percent": { "type": "number" } } } }, "memo": { "type": "string" }, "contactId": { "type": "string" } } }, "example": { "ids": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "splits": [ { "accountCode": "6120", "vatRatePercent": 15.0, "percent": 100.0 } ], "memo": "Fuel for the Cape Town delivery run", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "coded": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBankTransactionsByIdCodeResponse" } }, "ledgerNotice": { "type": "string" } } }, "example": { "coded": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "category": "6120 Bank Charges", "ledgerNotice": "R 1 380.00 posted to 6120 Bank Charges." } ], "ledgerNotice": "1 line coded to 6120." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-statements/profiles": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "Column-mapping profiles for the nine supported banks, plus any the tenant has saved.", "operationId": "getApiBankStatementsProfiles", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "banks": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "notes": { "type": "string" } } } }, "defaultBank": { "type": "string" }, "defaultBankLabel": { "type": "string" }, "migrationSource": { "type": "string" } } }, "example": { "banks": [ { "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "notes": "Budget deferred to the next financial year." } ], "defaultBank": "FNB", "defaultBankLabel": "Karoo Fresh Holdings Ltd", "migrationSource": "referral" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-statements/preview": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Parse an uploaded CSV, OFX or QIF and show what would be imported, without writing.", "operationId": "postApiBankStatementsPreview", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "filename", "in": "query", "required": false, "description": "The name to give the downloaded file.", "schema": { "type": "string" }, "example": "SignedPO-4417.pdf" }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "bank", "in": "query", "required": false, "schema": { "type": "string" }, "example": "fnb" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankStatementsConvertResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankStatementsConvertResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-statements/convert": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Turn the PDF or scan your bank sent into a statement. Multipart upload; answers with the transactions, whether they reconcile to the bank's own closing balance, and the text to post to /import. A locked PDF answers 200 with passwordRequired true and no rows (passwordRefused true when the password given did not open it): send it again with its password in the `password` form field, of at most 128 characters, used for that read only and kept nowhere. rowDoubts lists rows that contradict what they print; balances is false for those even at a nil difference.", "operationId": "postApiBankStatementsConvert", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "filename", "in": "query", "required": false, "description": "The name to give the downloaded file.", "schema": { "type": "string" }, "example": "SignedPO-4417.pdf" }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "bank", "in": "query", "required": false, "schema": { "type": "string" }, "example": "fnb" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankStatementsConvertResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankStatementsConvertResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-statements/import": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Commit a parsed statement. A statement with rows in rowDoubts answers 409 with code STATEMENT_ROWS_IN_DOUBT until confirmRowDoubts=true says a person has seen them.", "operationId": "postApiBankStatementsImport", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "filename", "in": "query", "required": false, "description": "The name to give the downloaded file.", "schema": { "type": "string" }, "example": "SignedPO-4417.pdf" }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "bank", "in": "query", "required": false, "schema": { "type": "string" }, "example": "fnb" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankAccountId": { "type": "string" }, "profile": { "type": "string" } } }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "profile": "fnb-csv" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string" }, "total": { "type": "integer" }, "imported": { "type": "integer" }, "duplicates": { "type": "integer" }, "rejected": { "type": "integer" }, "balances": { "type": "boolean" }, "balanceDifference": { "type": "number" }, "bankProfile": { "$ref": "#/components/schemas/PostApiBankStatementsImportResponseBankProfile" }, "issues": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "object" } }, "message": { "type": "string" } } }, "example": { "format": "CSV", "total": 2, "imported": 1, "duplicates": 1, "rejected": 0, "balances": true, "balanceDifference": 10005.0, "bankProfile": { "bank": "FNB", "label": "Karoo Fresh Holdings Ltd", "confidence": 1.0, "evidence": [ "text" ], "matched": false, "source": "referral" }, "issues": [], "warnings": [], "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-statements/export": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "Export transactions back out as CSV.", "operationId": "getApiBankStatementsExport", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "csv" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-rules": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "Auto-categorisation rules.", "operationId": "getApiBankRules", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBankRulesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "conditions": "text", "action": "created", "priority": 1, "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Banking & reconciliation" ], "summary": "Create a rule.", "operationId": "postApiBankRules", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBankRulesRequestConditionsItem" } }, "action": { "$ref": "#/components/schemas/PostApiBankRulesRequestAction" }, "priority": { "type": "integer" }, "matchMode": { "type": "string" }, "bankAccountId": { "type": "string" }, "applyOnImport": { "type": "boolean" }, "clientId": { "type": "string" } } }, "example": { "name": "Parking and toll fees", "conditions": [ { "field": "description", "op": "contains", "value": "PARKING|TOLL" } ], "action": { "category": "Travel", "createKind": "expense", "accountCode": "6120" }, "priority": 1, "matchMode": "all", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "applyOnImport": false, "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankRulesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankRulesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-rules/{id}": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "One rule.", "operationId": "getApiBankRulesById", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankRulesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankRulesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Banking & reconciliation" ], "summary": "Update a rule.", "operationId": "putApiBankRulesById", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBankRulesRequestConditionsItem" } }, "action": { "$ref": "#/components/schemas/PostApiBankRulesRequestAction" }, "priority": { "type": "integer" }, "isActive": { "type": "boolean" }, "matchMode": { "type": "string" }, "bankAccountId": { "type": "string" }, "clearBankAccount": { "type": "boolean" }, "applyOnImport": { "type": "boolean" } } }, "example": { "name": "Karoo Fresh Holdings Ltd", "conditions": [ { "field": "description", "op": "contains", "value": "PARKING|TOLL" } ], "action": { "category": "Travel", "createKind": "expense", "accountCode": "6120" }, "priority": 1, "isActive": true, "matchMode": "all", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clearBankAccount": false, "applyOnImport": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankRulesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankRulesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Banking & reconciliation" ], "summary": "Delete a rule.", "operationId": "deleteApiBankRulesById", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-rules/order": { "put": { "tags": [ "Banking & reconciliation" ], "summary": "Set the order the rules are tried in, most important first. The first rule that matches a line wins.", "operationId": "putApiBankRulesOrder", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleIds": { "type": "array", "items": { "type": "string" } } } }, "example": { "ruleIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "conditions": { "type": "string" }, "action": { "type": "string" }, "priority": { "type": "integer" }, "isActive": { "type": "boolean" }, "matchMode": { "type": "string" }, "bankAccountId": { "type": "null" }, "applyOnImport": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "conditions": "text", "action": "created", "priority": 1, "isActive": true, "matchMode": "all", "bankAccountId": null, "applyOnImport": false, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-rules/preview": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Show what the rules would do to the unreconciled transactions, before doing it.", "operationId": "postApiBankRulesPreview", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankRulesApplyResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankRulesApplyResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-rules/apply": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Apply the rules, creating the transactions they imply.", "operationId": "postApiBankRulesApply", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankAccountId": { "type": "string" } } }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankRulesApplyResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBankRulesApplyResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-rules/coded": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "The review queue: lines a bank rule coded that nobody has reviewed yet (reconciled lines are never listed). includeReviewed=true adds the reviewed ones.", "operationId": "getApiBankRulesCoded", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "includeReviewed", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "false" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "transactionId": { "type": "string" }, "bankAccountId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "type": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "createdKind": { "type": "string" }, "createdId": { "type": "string" }, "ruleAppliedAt": { "type": "string" } } } } } }, "example": { "total": 1, "lines": [ { "transactionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "type": "DEBIT", "category": "Office supplies", "status": "UNRECONCILED", "ruleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ruleName": "Karoo Fresh Holdings Ltd", "createdKind": "expense", "createdId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ruleAppliedAt": "2026-09-01T09:15:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-rules/coded/review": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Confirm the lines a rule coded: they leave the review queue. Send the ids, or all=true for every line waiting. A rule that codes a line again puts it back.", "operationId": "postApiBankRulesCodedReview", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "all": { "type": "boolean" } } }, "example": { "ids": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "all": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "reviewed": { "type": "integer" } } }, "example": { "reviewed": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reconciliation": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "Reconciliation sessions and their status ring.", "operationId": "getApiReconciliation", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bankAccountId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "open" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReconciliationByIdResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "statementBalance": 10005.0, "openingBalance": 10005.0, "clearedBalance": 10005.0, "difference": 1.0, "clearedIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "status": "OPEN", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reconciliation/start": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Open a reconciliation to a statement date and closing balance.", "operationId": "postApiReconciliationStart", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankAccountId": { "type": "string" }, "statementBalance": { "type": "number" }, "openingBalance": { "type": "number" } } }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "statementBalance": 1500.0, "openingBalance": 10005.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReconciliationByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReconciliationByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reconciliation/{id}": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "One session — cleared, uncleared and the difference still to explain.", "operationId": "getApiReconciliationById", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReconciliationByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReconciliationByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reconciliation/{id}/clear/{transactionId}": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Tick a transaction as appearing on the statement.", "operationId": "postApiReconciliationByIdClearByTransactionId", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReconciliationByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReconciliationByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reconciliation/{id}/unclear/{transactionId}": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Untick it.", "operationId": "postApiReconciliationByIdUnclearByTransactionId", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReconciliationByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReconciliationByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reconciliation/{id}/clear": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Tick several transactions as appearing on the statement, in one request. All or nothing: a line not on the account, or already reconciled elsewhere, refuses the whole request.", "operationId": "postApiReconciliationByIdClear", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReconciliationByIdClearRequest" }, "example": { "transactionIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReconciliationByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReconciliationByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reconciliation/{id}/unclear": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Untick several transactions at once.", "operationId": "postApiReconciliationByIdUnclear", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReconciliationByIdClearRequest" }, "example": { "transactionIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "bankAccountId": { "type": "string" }, "statementBalance": { "type": "number" }, "openingBalance": { "type": "number" }, "clearedBalance": { "type": "number" }, "difference": { "type": "number" }, "clearedIds": { "type": "array", "items": { "type": "object" } }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "statementBalance": 10005.0, "openingBalance": 10005.0, "clearedBalance": 10005.0, "difference": 1.0, "clearedIds": [], "status": "OPEN", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reconciliation/{id}/finalise": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Close the reconciliation. Refused while the difference is non-zero, and while the books do not tie to the statement.", "operationId": "postApiReconciliationByIdFinalise", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReconciliationByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReconciliationByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reconciliation/{id}/reopen": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Reopen a finalised reconciliation.", "operationId": "postApiReconciliationByIdReopen", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReconciliationByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReconciliationByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reconciliation/{id}/abandon": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Close an open reconciliation without finalising it, so the account can start a fresh one.", "operationId": "postApiReconciliationByIdAbandon", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReconciliationByIdResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "statementBalance": 10005.0, "openingBalance": 10005.0, "clearedBalance": 10005.0, "difference": 1.0, "clearedIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "status": "ABANDONED", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/{id}/coding-suggestion": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "How this company coded this payee last time, and how many times in a row — a count, never a confidence.", "operationId": "getApiBankTransactionsByIdCodingSuggestion", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string" }, "vatRate": { "type": "number" }, "reason": { "type": "string" }, "timesCoded": { "type": "integer" }, "payeeKey": { "type": "string" } } }, "example": { "category": "Meals & Entertainment", "vatRate": 0.0, "reason": "OCEAN BASKET — coded this way 4 times.", "timesCoded": 4, "payeeKey": "ocean basket" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/{id}/attachments": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "The paperwork attached to this statement line.", "operationId": "getApiBankTransactionsByIdAttachments", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "attachmentId": { "type": "string" }, "filename": { "type": "string" }, "caption": { "type": "null" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "sequence": { "type": "integer" }, "uploadedByName": { "type": "string" }, "fromInboxId": { "type": "null" }, "createdAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "filename": "ocean-basket.jpg", "caption": null, "contentType": "image/jpeg", "sizeBytes": 184320, "sequence": 1, "uploadedByName": "Thabo Nkosi", "fromInboxId": null, "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Banking & reconciliation" ], "summary": "Attach a receipt to this line. Raw bytes, never multipart; the server decides the stored type and the object key.", "operationId": "postApiBankTransactionsByIdAttachments", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "filename", "in": "query", "required": false, "description": "The name to give the downloaded file.", "schema": { "type": "string" }, "example": "till-slip-engen.pdf" }, { "name": "contentType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "application/pdf" }, { "name": "caption", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Till%20slip%20for%20the%20fuel" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "attachmentId": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "sequence": { "type": "integer" }, "createdAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "filename": "ocean-basket.jpg", "contentType": "image/jpeg", "sizeBytes": 184320, "sequence": 1, "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/{id}/attachments/from-inbox": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Accept a proposal: link a document the inbox has already filed. No bytes move and no second copy is stored.", "operationId": "postApiBankTransactionsByIdAttachmentsFromInbox", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "attachmentId": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "sequence": { "type": "integer" }, "fromInboxId": { "type": "string" }, "createdAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "filename": "receipt.pdf", "contentType": "application/pdf", "sizeBytes": 91204, "sequence": 2, "fromInboxId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/{id}/attachments/{linkId}": { "delete": { "tags": [ "Banking & reconciliation" ], "summary": "Take a file off this line. The file itself is kept — an expense that uses it is untouched.", "operationId": "deleteApiBankTransactionsByIdAttachmentsByLinkId", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/{id}/attachment-proposals": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "Filed documents of the same amount within a few days of this line. Proposals; nothing is attached.", "operationId": "getApiBankTransactionsByIdAttachmentProposals", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "inboxId": { "type": "string" }, "attachmentId": { "type": "string" }, "filename": { "type": "string" }, "supplierName": { "type": "string" }, "documentDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "daysApart": { "type": "integer" }, "sentence": { "type": "string" } } } }, "example": [ { "inboxId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "filename": "receipt.pdf", "supplierName": "Ocean Basket", "documentDate": "2026-08-30", "amount": 1850.0, "daysApart": 2, "sentence": "Ocean Basket is for the same amount and is dated 2 days earlier. Attach it to this line?" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-accounts/{accountId}/imports": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "Every statement read into this account, newest first, and how many lines each still has.", "operationId": "getApiBankAccountsByAccountIdImports", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "imports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "bankAccountId": { "type": "string" }, "source": { "type": "string" }, "label": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "lineCount": { "type": "integer" }, "duplicateCount": { "type": "integer" }, "linesRemaining": { "type": "integer" }, "importedAt": { "type": "string" }, "importedByName": { "type": "string" } } } }, "unbatchedLines": { "type": "integer" }, "unbatchedNote": { "type": "string" } } }, "example": { "imports": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "source": "upload", "label": "fnb-gold-july-2026.pdf", "periodStart": "2026-07-01", "periodEnd": "2026-07-31", "lineCount": 8, "duplicateCount": 2, "linesRemaining": 8, "importedAt": "2026-09-01T09:15:00Z", "importedByName": "Thabo Nkosi" } ], "unbatchedLines": 14, "unbatchedNote": "Lines imported before Ledgr started recording imports are not grouped into one." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-imports/{batchId}/undo-preview": { "get": { "tags": [ "Banking & reconciliation" ], "summary": "What undoing this import would remove, and what it could not — before anything is removed.", "operationId": "getApiBankImportsByBatchIdUndoPreview", "description": "Requires the `banking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "integer" }, "kept": { "type": "integer" }, "sentence": { "type": "string" }, "keptLines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "why": { "type": "string" } } } } } }, "example": { "removed": 6, "kept": 2, "sentence": "Removes 6 lines of the 8 lines this import added. 2 lines stay — 1 is in a finalised reconciliation and 1 is matched to a document.", "keptLines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "why": "This line is reconciled." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-imports/{batchId}/undo": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Remove what this import added. Never refuses wholesale, and names every line it could not take.", "operationId": "postApiBankImportsByBatchIdUndo", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankImportsByBatchIdUndoResponse" }, "example": { "removed": 6, "kept": 2, "sentence": "Removed 6 lines of the 8 lines this import added. 2 lines stay — 1 is in a finalised reconciliation and 1 is matched to a document.", "keptLines": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bank-transactions/bulk-delete": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Remove several ticked statement lines at once, by the same rule the single delete uses.", "operationId": "postApiBankTransactionsBulkDelete", "description": "Requires the `banking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "banking:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBankImportsByBatchIdUndoResponse" }, "example": { "removed": 1, "kept": 0, "sentence": "Removed 1 line of the 1 line this import added.", "keptLines": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/accounts": { "get": { "tags": [ "General ledger" ], "summary": "The chart of accounts.", "operationId": "getApiAccounts", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Restrict to one type. Matched case-insensitively; an unrecognised value is refused.", "schema": { "type": "string" }, "example": "expense" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiAccountsResponse" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiAccountsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "General ledger" ], "summary": "Add an account.", "operationId": "postApiAccounts", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "accountType": { "type": "string" }, "accountSubtype": { "type": "string" }, "normalBalance": { "type": "string" }, "parentId": { "type": "string" }, "currency": { "type": "string" }, "isSystem": { "type": "boolean" } } }, "example": { "code": "6340", "name": "Delivery Costs", "description": "Courier and freight on goods sold", "accountType": "expense", "accountSubtype": "operating", "normalBalance": "debit", "parentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "currency": "ZAR", "isSystem": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiAccountsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiAccountsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/accounts/{id}/merge": { "post": { "tags": [ "General ledger" ], "summary": "Move an account's balance into another of the same type by a journal dated `date`, then retire it. Posted lines are never rewritten; an income or expense account moves this financial year only.", "operationId": "postApiAccountsByIdMerge", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "intoAccountId": { "type": "string" }, "date": { "type": "string", "format": "date" } } }, "example": { "intoAccountId": "7c2e9b14-0d3a-4f6e-8b21-5a9c1d7e3f40", "date": "2026-10-31" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "journalNumber": { "type": "string" }, "moved": { "type": "number" } } }, "example": { "journalNumber": "JE-2026-000124", "moved": 300.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/accounts/tree": { "get": { "tags": [ "General ledger" ], "summary": "The chart as a tree, for the picker.", "operationId": "getApiAccountsTree", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiAccountsResponse" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiAccountsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/accounts/{id}": { "get": { "tags": [ "General ledger" ], "summary": "One account with its balance.", "operationId": "getApiAccountsById", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiAccountsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiAccountsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "General ledger" ], "summary": "Rename or recode an account. Setting accountSubtype to investment_in_subsidiary marks a non-current asset account (no other subtype) as the holding company's investment in a subsidiary, which the group balance sheet eliminates; a blank takes that mark off. Any other subtype is stored as given. Setting statementClass (for example other_current on an asset) moves the account to another line of the annual statements and its lead schedule without touching its posting subtype; blank puts it back where the chart classifies it, and cash, bank and register-owned accounts are refused.", "operationId": "putApiAccountsById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "accountSubtype": { "type": "string" }, "isActive": { "type": "boolean" }, "publicBenefitReceipts": { "type": "boolean" }, "pboReceipts": { "type": "string" }, "pboBearsGeneralCosts": { "type": "boolean" }, "pboExpenditure": { "type": "string" }, "itr14Treatment": { "type": "string" }, "statementClass": { "type": "string" } } }, "example": { "name": "Stock write-offs and shrinkage", "description": "Consulting services — August 2026", "accountSubtype": "operating", "isActive": true, "publicBenefitReceipts": false, "pboReceipts": "permissible", "pboBearsGeneralCosts": true, "pboExpenditure": "trading", "itr14Treatment": "none", "statementClass": "other_current" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiAccountsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiAccountsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "General ledger" ], "summary": "Delete an account. Refused while journal lines, invoice lines or quote lines reference it — which is why the Quotes tables survive the route being unmounted.", "operationId": "deleteApiAccountsById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/journals": { "get": { "tags": [ "General ledger" ], "summary": "Manual journals.", "operationId": "getApiLedgerJournals", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "sourceType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "invoice" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerJournalsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "journalNumber": "INV-0001", "journalDate": "2026-09-01", "sourceType": "invoice", "sourceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "memo": "text", "status": "sent", "totalDebit": 10005.0, "totalCredit": 10005.0, "reversedBy": "text", "reverses": "text", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountCode": "CT-001", "accountName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "debit": 1.0, "credit": 1.0, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "editable": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "General ledger" ], "summary": "Post a manual journal. Refused unless it balances and the period is open.", "operationId": "postApiLedgerJournals", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reverseOn": { "type": "string", "format": "date" }, "journalDate": { "type": "string", "format": "date" }, "memo": { "type": "string" }, "reference": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerJournalsRequestLinesItem" } }, "post": { "type": "boolean" }, "clientId": { "type": "string" } } }, "example": { "reverseOn": "2026-10-01", "journalDate": "2026-08-31", "memo": "Depreciation for August", "reference": "JNL-0042", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountCode": "CT-001", "accountName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "debit": 4166.67, "credit": 0.0, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountCode": "CT-001", "accountName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "debit": 0.0, "credit": 4166.67, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "post": true, "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLedgerJournalsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLedgerJournalsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/journals/{id}": { "get": { "tags": [ "General ledger" ], "summary": "One journal and its lines.", "operationId": "getApiLedgerJournalsById", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLedgerJournalsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLedgerJournalsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "General ledger" ], "summary": "Delete a draft journal. A posted journal is reversed, never deleted.", "operationId": "deleteApiLedgerJournalsById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/journals/{id}/reverse": { "post": { "tags": [ "General ledger" ], "summary": "Post the contra. Never edits the original.", "operationId": "postApiLedgerJournalsByIdReverse", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLedgerBooksOpenResponse" }, "example": { "date": "2026-09-01" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLedgerJournalsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLedgerJournalsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/journals/{id}/post": { "post": { "tags": [ "General ledger" ], "summary": "Post a draft journal, under the period lock and balance check a direct post meets. Only a draft is posted.", "operationId": "postApiLedgerJournalsByIdPost", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLedgerJournalsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLedgerJournalsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/recurring-journals": { "get": { "tags": [ "General ledger" ], "summary": "Recurring journals of the active company, each with its lines and newest occurrences.", "operationId": "getApiLedgerRecurringJournals", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerRecurringJournalsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "memo": "text", "reference": "INV-0001", "frequency": "monthly", "startDate": "2026-09-01", "endDate": "2026-09-30", "nextDate": "2026-09-01", "status": "active", "totalDebit": 10005.0, "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountCode": "CT-001", "accountName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "debit": 1.0, "credit": 1.0, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis2Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "analysis3Id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "runs": [ { "occurrenceDate": "2026-09-01", "outcome": "posted", "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "journalNumber": "INV-0001", "reason": "Budget deferred to the next financial year." } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "General ledger" ], "summary": "Start a recurring journal. Its lines meet a hand-typed journal's checks; it posts on each occurrence date from startDate.", "operationId": "postApiLedgerRecurringJournals", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memo": { "type": "string" }, "reference": { "type": "string" }, "frequency": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "debit": { "type": "number" }, "credit": { "type": "number" } } } }, "clientId": { "type": "string" } } }, "example": { "memo": "Accrue the audit fee", "reference": "AUDIT-ACCRUAL", "frequency": "monthly", "startDate": "2026-11-01", "endDate": "2027-02-28", "lines": [ { "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "debit": 4500.0 }, { "accountId": "7c2e9b14-0d3a-4f6e-8b21-5a9c1d7e3f40", "credit": 4500.0 } ], "clientId": "9b3d6e21-4c7a-4f18-a0d5-2e8f1c6b7a94" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLedgerRecurringJournalsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLedgerRecurringJournalsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/recurring-journals/{id}/status": { "put": { "tags": [ "General ledger" ], "summary": "Pause, resume or end a recurring journal. A resumed one picks up at its next date on or after today.", "operationId": "putApiLedgerRecurringJournalsByIdStatus", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "paused" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLedgerRecurringJournalsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLedgerRecurringJournalsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/books-open": { "get": { "tags": [ "General ledger" ], "summary": "The day after the opening balances, or null when there are none. A journal dated before it posts, with a notice.", "operationId": "getApiLedgerBooksOpen", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLedgerBooksOpenResponse" }, "example": { "date": "2026-11-01" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/journal-batches": { "get": { "tags": [ "General ledger" ], "summary": "Journal batches of the active company, open ones first.", "operationId": "getApiLedgerJournalBatches", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string" }, "lineCount": { "type": "integer" }, "totalDebit": { "type": "number" }, "totalCredit": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object" } }, "journals": { "type": "array", "items": { "type": "object" } }, "createdAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "October payroll", "reference": "BUR-10", "status": "open", "lineCount": 24, "totalDebit": 185000.0, "totalCredit": 185000.0, "lines": [], "journals": [], "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "General ledger" ], "summary": "Keep a worksheet of journal lines. Unfinished lines are allowed; only posting judges them.", "operationId": "postApiLedgerJournalBatches", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "reference": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerJournalBatchesRequestLinesItem" } }, "clientId": { "type": "string" } } }, "example": { "name": "October payroll", "reference": "BUR-10", "lines": [ { "journalDate": "2026-10-31", "accountCode": "6200", "description": "Gross salaries", "debit": 185000.0 }, { "journalDate": "2026-10-31", "accountCode": "2150", "credit": 185000.0 } ], "clientId": "9b3d6e21-4c7a-4f18-a0d5-2e8f1c6b7a94" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string" }, "lineCount": { "type": "integer" }, "totalDebit": { "type": "number" }, "totalCredit": { "type": "number" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerJournalBatchesRequestLinesItem" } }, "journals": { "type": "array", "items": { "type": "object" } } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "October payroll", "reference": "BUR-10", "status": "open", "lineCount": 2, "totalDebit": 185000.0, "totalCredit": 185000.0, "lines": [ { "journalDate": "2026-10-31", "accountCode": "6200", "description": "Gross salaries", "debit": 185000.0, "credit": 0.0 } ], "journals": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/journal-batches/{id}": { "get": { "tags": [ "General ledger" ], "summary": "A batch with its lines, and the journals it posted once it has.", "operationId": "getApiLedgerJournalBatchesById", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "lineCount": { "type": "integer" }, "totalDebit": { "type": "number" }, "totalCredit": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object" } }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLedgerJournalBatchesByIdResponseJournalsItem" } }, "postedAt": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "October payroll", "status": "posted", "lineCount": 2, "totalDebit": 185000.0, "totalCredit": 185000.0, "lines": [], "journals": [ { "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "journalNumber": "JE-2026-000120", "journalDate": "2026-10-31", "total": 185000.0 } ], "postedAt": "2026-11-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "General ledger" ], "summary": "Replace an open batch's name and lines. A posted batch cannot be changed.", "operationId": "putApiLedgerJournalBatchesById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "reference": { "type": "string" }, "clientId": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "journalDate": { "type": "string", "format": "date" }, "accountCode": { "type": "string" }, "debit": { "type": "number" }, "credit": { "type": "number" } } } } } }, "example": { "name": "October payroll", "reference": "BUR-10", "clientId": "9b3d6e21-4c7a-4f18-a0d5-2e8f1c6b7a94", "lines": [ { "journalDate": "2026-10-31", "accountCode": "6200", "debit": 185000.0 }, { "journalDate": "2026-10-31", "accountCode": "2150", "credit": 185000.0 } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "lineCount": { "type": "integer" }, "totalDebit": { "type": "number" }, "totalCredit": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object" } }, "journals": { "type": "array", "items": { "type": "object" } } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "October payroll", "status": "open", "lineCount": 2, "totalDebit": 185000.0, "totalCredit": 185000.0, "lines": [], "journals": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "General ledger" ], "summary": "Throw an open batch away. Nothing reached the ledger, so nothing is undone.", "operationId": "deleteApiLedgerJournalBatchesById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/journal-batches/{id}/post": { "post": { "tags": [ "General ledger" ], "summary": "Post a batch as one journal per date, all of them or none. Each date must balance. Posting a posted batch moves nothing.", "operationId": "postApiLedgerJournalBatchesByIdPost", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "lineCount": { "type": "integer" }, "totalDebit": { "type": "number" }, "totalCredit": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object" } }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLedgerJournalBatchesByIdResponseJournalsItem" } } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "October payroll", "status": "posted", "lineCount": 2, "totalDebit": 185000.0, "totalCredit": 185000.0, "lines": [], "journals": [ { "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "journalNumber": "JE-2026-000120", "journalDate": "2026-10-31", "total": 185000.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/{id}/seller-declaration": { "post": { "tags": [ "General ledger" ], "summary": "Keep the second-hand seller's signed declaration (VAT264) on the bill: the raw bytes as the body, the name and the day it was signed in the query. Notional input tax on the bill's second-hand lines is claimed only while it is held.", "operationId": "postApiBillsByIdSellerDeclaration", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "filename", "in": "query", "required": false, "description": "The name to give the downloaded file.", "schema": { "type": "string" }, "example": "vat264.pdf" }, { "name": "contentType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "application/pdf" }, { "name": "signedOn", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "billId": { "type": "string" }, "sellerDeclarationUrl": { "type": "string" }, "sellerDeclarationSignedOn": { "type": "string", "format": "date" } } }, "example": { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sellerDeclarationUrl": "/api/files/7c2e9b14-0d3a-4f6e-8b21-5a9c1d7e3f40", "sellerDeclarationSignedOn": "2026-09-01" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "General ledger" ], "summary": "Take the seller's declaration off a bill. The file is kept; the notional input tax it substantiated is taken back.", "operationId": "deleteApiBillsByIdSellerDeclaration", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "billId": { "type": "string" }, "sellerDeclarationUrl": { "type": "null" }, "sellerDeclarationSignedOn": { "type": "null" } } }, "example": { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sellerDeclarationUrl": null, "sellerDeclarationSignedOn": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/journals/{id}/attachments": { "get": { "tags": [ "General ledger" ], "summary": "The working papers on a journal.", "operationId": "getApiLedgerJournalsByIdAttachments", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLedgerJournalsByIdAttachmentsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiLedgerJournalsByIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "General ledger" ], "summary": "Attach a file to a journal: the raw bytes as the body, the name in the query. A posted journal takes files too.", "operationId": "postApiLedgerJournalsByIdAttachments", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "filename", "in": "query", "required": false, "description": "The name to give the downloaded file.", "schema": { "type": "string" }, "example": "working-paper.pdf" }, { "name": "contentType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "application/pdf" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLedgerJournalsByIdAttachmentsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiLedgerJournalsByIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/journals/{id}/attachments/{linkId}": { "delete": { "tags": [ "General ledger" ], "summary": "Take a file off a journal. The file is kept.", "operationId": "deleteApiLedgerJournalsByIdAttachmentsByLinkId", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/budget-scenarios": { "get": { "tags": [ "General ledger" ], "summary": "The named budgets this company holds. `Main` is always among them.", "operationId": "getApiLedgerBudgetScenarios", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Bank", "Main" ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/account-budgets/seed": { "post": { "tags": [ "General ledger" ], "summary": "Fill a named budget from last year's actuals, month for month, lifted by a percentage. Seeding again replaces.", "operationId": "postApiLedgerAccountBudgetsSeed", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scenario": { "type": "string" }, "yearStart": { "type": "string", "format": "date" }, "upliftPercent": { "type": "number" } } }, "example": { "scenario": "Bank", "yearStart": "2026-03-01", "upliftPercent": 10.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLedgerAccountBudgetsResponse" }, "example": { "saved": 48 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/periods": { "get": { "tags": [ "General ledger" ], "summary": "Accounting periods and their lock state.", "operationId": "getApiLedgerPeriods", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerPeriodsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "label": "Karoo Fresh Holdings Ltd", "status": "sent", "closedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "General ledger" ], "summary": "Open a period.", "operationId": "postApiLedgerPeriods", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "label": { "type": "string" } } }, "example": { "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "label": "September 2026" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLedgerPeriodsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "label": "Karoo Fresh Holdings Ltd", "status": "sent", "closedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/periods/{id}/status": { "put": { "tags": [ "General ledger" ], "summary": "Lock or unlock a period. A locked period refuses every posting, including automatic ones.", "operationId": "putApiLedgerPeriodsByIdStatus", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "locked" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLedgerPeriodsByIdReviewResponse" }, "examples": { "default": { "$ref": "#/components/examples/PutApiLedgerPeriodsByIdReviewResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/periods/{id}/review": { "put": { "tags": [ "General ledger" ], "summary": "A reviewer signs a closed or locked period off. Needs reports:approve; the person who closed it does not review it while somebody else can. Reopening the period takes the sign-off off.", "operationId": "putApiLedgerPeriodsByIdReview", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLedgerPeriodsByIdReviewResponse" }, "examples": { "default": { "$ref": "#/components/examples/PutApiLedgerPeriodsByIdReviewResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/journal-approval-policy": { "get": { "tags": [ "General ledger" ], "summary": "The amount from which a hand-typed journal is posted by a second person who can approve, not by the person who made it. Null: one person posts at every amount.", "operationId": "getApiLedgerJournalApprovalPolicy", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesApprovalPolicyResponse" }, "example": { "secondApprovalFrom": 1.0, "approvers": 1, "mayChange": false, "summary": "Consulting services — August 2026" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "General ledger" ], "summary": "Set the amount from which a manual journal needs a second person to post it, or turn it off with null. The owner or an admin who can approve reports.", "operationId": "putApiLedgerJournalApprovalPolicy", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiExpensesApprovalPolicyRequest" }, "example": { "secondApprovalFrom": 10000.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesApprovalPolicyResponse" }, "example": { "secondApprovalFrom": 1.0, "approvers": 1, "mayChange": false, "summary": "Consulting services — August 2026" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/cost-centres": { "get": { "tags": [ "General ledger" ], "summary": "Cost centres — or, with dimension=2 or 3, the values of the tenant's second or third analysis dimension.", "operationId": "getApiLedgerCostCentres", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dimension", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerCostCentresResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "kind": "standard", "parentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "General ledger" ], "summary": "Add a cost centre.", "operationId": "postApiLedgerCostCentres", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "parentId": { "type": "string" }, "isActive": { "type": "boolean" }, "dimension": { "type": "integer" }, "restricted": { "type": "boolean" } } }, "example": { "code": "CPT", "name": "Cape Town branch", "description": "Consulting services — August 2026", "kind": "department", "parentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true, "dimension": 1, "restricted": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLedgerCostCentresResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLedgerCostCentresResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/analysis-dimensions": { "get": { "tags": [ "General ledger" ], "summary": "The company's three analysis dimensions and their names. Dimension 1 is the cost centre and always on; 2 and 3 (a project, a fund) are on once named. A dimension's values are cost centres created with that dimension, listed by GET /api/ledger/cost-centres?dimension=2.", "operationId": "getApiLedgerAnalysisDimensions", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLedgerAnalysisDimensionsResponseItem" } }, "example": [ { "slot": 1, "name": "Cost centre", "enabled": true }, { "slot": 2, "name": "Project", "enabled": true }, { "slot": 3, "name": "Dimension 3", "enabled": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "General ledger" ], "summary": "Name dimensions 2 and 3. A blank name switches the dimension off for new documents; postings already tagged keep their values and still report.", "operationId": "putApiLedgerAnalysisDimensions", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dimension2": { "type": "string" }, "dimension3": { "type": "string" } } }, "example": { "dimension2": "Project", "dimension3": "Fund" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLedgerAnalysisDimensionsResponseItem" } }, "example": [ { "slot": 1, "name": "Cost centre", "enabled": true }, { "slot": 2, "name": "Project", "enabled": true }, { "slot": 3, "name": "Fund", "enabled": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/cost-centres/{id}": { "put": { "tags": [ "General ledger" ], "summary": "Rename a cost centre.", "operationId": "putApiLedgerCostCentresById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "parentId": { "type": "string" }, "isActive": { "type": "boolean" }, "restricted": { "type": "boolean" } } }, "example": { "code": "CPT", "name": "Cape Town Depot", "description": "Consulting services — August 2026", "kind": "branch", "parentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true, "restricted": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLedgerCostCentresResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLedgerCostCentresResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "General ledger" ], "summary": "Remove a cost centre.", "operationId": "deleteApiLedgerCostCentresById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/account-budgets": { "get": { "tags": [ "General ledger" ], "summary": "Budgets per ledger account and period.", "operationId": "getApiLedgerAccountBudgets", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "scenario", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Main" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "accountCode": { "type": "string" }, "accountName": { "type": "string" }, "accountType": { "type": "string" }, "periodMonth": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "costCentreId": { "type": "string" }, "costCentreCode": { "type": "string" }, "notes": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountCode": "CT-001", "accountName": "Karoo Fresh Holdings Ltd", "accountType": "asset", "periodMonth": "2026-09-01", "amount": 10005.0, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreCode": "CT-001", "notes": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "General ledger" ], "summary": "Set a budget line.", "operationId": "putApiLedgerAccountBudgets", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "budgets": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "periodMonth": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "costCentreId": { "type": "string" }, "notes": { "type": "string" } } } } } }, "example": { "budgets": [ { "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodMonth": "2026-09-01", "amount": 45000.0, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Approved at the August board meeting" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLedgerAccountBudgetsResponse" }, "example": { "saved": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/account-budgets/{id}": { "delete": { "tags": [ "General ledger" ], "summary": "Remove a budget line.", "operationId": "deleteApiLedgerAccountBudgetsById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/budget-by-account": { "get": { "tags": [ "General ledger" ], "summary": "Budget against actual, by account.", "operationId": "getApiLedgerBudgetByAccount", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "scenario", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Main" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "periodLabel": { "type": "string" }, "revenue": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLedgerBudgetByAccountResponseRevenueItem" } }, "costOfSales": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLedgerBudgetByAccountResponseRevenueItem" } }, "expenses": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLedgerBudgetByAccountResponseRevenueItem" } }, "totalBudgetedRevenue": { "type": "number" }, "totalActualRevenue": { "type": "number" }, "totalBudgetedCost": { "type": "number" }, "totalActualCost": { "type": "number" }, "budgetedProfit": { "type": "number" }, "actualProfit": { "type": "number" }, "empty": { "type": "boolean" } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "periodLabel": "2026-09", "revenue": [ { "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "accountType": "asset", "budget": 1.0, "actual": 1.0, "variance": 1.0, "variancePct": 1.0 } ], "costOfSales": [ { "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "accountType": "asset", "budget": 1.0, "actual": 1.0, "variance": 1.0, "variancePct": 1.0 } ], "expenses": [ { "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "accountType": "asset", "budget": 1.0, "actual": 1.0, "variance": 1.0, "variancePct": 1.0 } ], "totalBudgetedRevenue": 10005.0, "totalActualRevenue": 10005.0, "totalBudgetedCost": 10005.0, "totalActualCost": 10005.0, "budgetedProfit": 1.0, "actualProfit": 1.0, "empty": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/fx-revaluations": { "get": { "tags": [ "General ledger" ], "summary": "Period-end FX revaluations already posted.", "operationId": "getApiLedgerFxRevaluations", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerFxRevaluationResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodEnd": "2026-09-30", "baseCurrency": "ZAR", "netAdjustment": 8700.0, "documentsRevalued": 1, "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lines": [ { "sourceType": "invoice", "sourceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "currency": "ZAR", "outstanding": 1.0, "bookedRate": 15.0, "closingRate": 15.0, "bookedBase": 1.0, "restatedBase": 1.0, "adjustment": 1.0 } ], "missingRates": [ "text" ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/fx-revaluation": { "post": { "tags": [ "General ledger" ], "summary": "Revalue foreign-currency balances (invoices, credit notes, customers' kept credit, bills and foreign bank accounts) at the closing rate and post the difference. The closing rate is the newest rate on or before the period end, a rate typed for that very day first; an older typed rate is not carried forward past a newer published one (IFRS for SMEs 30.9).", "operationId": "postApiLedgerFxRevaluation", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "periodEnd", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "type": "string", "format": "date" } } }, "example": { "asOf": "2026-08-31" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLedgerFxRevaluationResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodEnd": "2026-09-30", "baseCurrency": "ZAR", "netAdjustment": 8700.0, "documentsRevalued": 1, "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lines": [ { "sourceType": "invoice", "sourceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "currency": "ZAR", "outstanding": 1.0, "bookedRate": 15.0, "closingRate": 15.0, "bookedBase": 1.0, "restatedBase": 1.0, "adjustment": 1.0 } ], "missingRates": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/health": { "get": { "tags": [ "General ledger" ], "summary": "Control-account checks — each control account against the record that explains it, as at today: 1320 against aged debtors, 2110 against aged creditors, 1310 against the stock valuation, the VAT accounts against what SARS is owed, 2140–2142 against the EMP201s and payslips, 1315 work in progress against open work orders and job-card parts, the fixed asset cost and accumulated depreciation against the asset register, each bank account with a statement against its closing balance, each loan account and 2121 against the loan register, and 2115 GRNI against the goods received and not yet invoiced. The year-end checklist strikes the same ties as at the year end.", "operationId": "getApiLedgerHealth", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "journals": { "type": "integer" }, "posted": { "type": "integer" }, "reversed": { "type": "integer" }, "draft": { "type": "integer" }, "unbalancedJournals": { "type": "integer" }, "chartAccounts": { "type": "integer" }, "chartSeeded": { "type": "boolean" } } }, "example": { "journals": 1, "posted": 1, "reversed": 1, "draft": 1, "unbalancedJournals": 1, "chartAccounts": 3, "chartSeeded": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/rebuild": { "post": { "tags": [ "General ledger" ], "summary": "Rebuild the ledger from source documents. The repair of last resort, not a routine.", "operationId": "postApiLedgerRebuild", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "integer" }, "payments": { "type": "integer" }, "bills": { "type": "integer" }, "billPayments": { "type": "integer" }, "expenses": { "type": "integer" }, "payrollRuns": { "type": "integer" }, "journalsPosted": { "type": "integer" }, "failures": { "type": "array", "items": { "type": "object" } } } }, "example": { "invoices": 1, "payments": 1, "bills": 1, "billPayments": 1, "expenses": 1, "payrollRuns": 1, "journalsPosted": 1, "failures": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/seed-chart": { "post": { "tags": [ "General ledger" ], "summary": "Seed a standard SA chart of accounts into an empty tenant.", "operationId": "postApiLedgerSeedChart", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountsCreated": { "type": "integer" } } }, "example": { "accountsCreated": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fx/rates": { "get": { "tags": [ "General ledger" ], "summary": "Exchange rates held, and how old each one is; with asOf, the rates a document dated that day converts at.", "operationId": "getApiFxRates", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "base", "in": "query", "required": false, "schema": { "type": "string" }, "example": "ZAR" }, { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiFxRatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiFxRatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "General ledger" ], "summary": "Record a rate by hand.", "operationId": "putApiFxRates", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromCurrency": { "type": "string" }, "toCurrency": { "type": "string" }, "rate": { "type": "number" }, "asOf": { "type": "string", "format": "date" } } }, "example": { "fromCurrency": "ZAR", "toCurrency": "ZAR", "rate": 15.0, "asOf": "2026-09-30" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiFxRatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiFxRatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fx/rates/{from}": { "delete": { "tags": [ "General ledger" ], "summary": "Put one currency back on the published rate, clearing what was entered by hand.", "operationId": "deleteApiFxRatesByFrom", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "cleared": { "type": "boolean" }, "message": { "type": "string" }, "rates": { "type": "object", "properties": { "baseCurrency": { "type": "string" }, "rates": { "type": "array", "items": { "type": "object", "properties": { "fromCurrency": { "type": "string" }, "toCurrency": { "type": "string" }, "rate": { "type": "number" }, "asOf": { "type": "string", "format": "date" }, "source": { "type": "string" }, "fetchedAt": { "type": "string" }, "stale": { "type": "boolean" } } } }, "anyStale": { "type": "boolean" }, "summary": { "type": "string" } } } } }, "example": { "cleared": true, "message": "EUR is back on the published rate. Refresh to fetch today's.", "rates": { "baseCurrency": "ZAR", "rates": [ { "fromCurrency": "EUR", "toCurrency": "ZAR", "rate": 19.74, "asOf": "2026-09-19", "source": "ecb", "fetchedAt": "2026-09-19T09:15:00Z", "stale": false } ], "anyStale": false, "summary": "Consulting services — August 2026" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fx/refresh": { "post": { "tags": [ "General ledger" ], "summary": "Fetch the latest rates from the ECB.", "operationId": "postApiFxRefresh", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "source": { "type": "string" }, "asOf": { "type": "string" }, "inserted": { "type": "integer" }, "updated": { "type": "integer" }, "skippedManual": { "type": "integer" }, "currencies": { "type": "array", "items": { "type": "string" } }, "fromCache": { "type": "boolean" }, "fetchedMinutesAgo": { "type": "integer" }, "failureReason": { "type": "string" } } }, "example": { "ok": true, "source": "referral", "asOf": "text", "inserted": 1, "updated": 1, "skippedManual": 1, "currencies": [ "text" ], "fromCache": false, "fetchedMinutesAgo": 1, "failureReason": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fixed-assets": { "get": { "tags": [ "General ledger" ], "summary": "The asset register.", "operationId": "getApiFixedAssets", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "includeDisposed", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "type": "string" }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiFixedAssetsResponse" } }, "totalCost": { "type": "number" }, "totalAccumulatedDepreciation": { "type": "number" }, "totalBookValue": { "type": "number" }, "byClass": { "type": "array", "items": { "type": "object", "properties": { "assetClass": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" }, "cost": { "type": "number" }, "accumulatedDepreciation": { "type": "number" }, "bookValue": { "type": "number" } } } }, "periodsOutstanding": { "type": "integer" } } }, "example": { "asOf": "text", "assets": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "assetNumber": "INV-0001", "name": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "assetClass": "text", "assetClassLabel": "Karoo Fresh Holdings Ltd", "acquisitionDate": "2026-09-01", "cost": 10005.0, "residualValue": 10005.0, "usefulLifeMonths": 1, "usefulLifeReliable": true, "method": "eft", "ratePercent": 15.0, "accumulatedDepreciation": 1.0, "bookValue": 10005.0, "depreciatedTo": "2026-09-30", "status": "sent", "disposalDate": "2026-09-01", "disposalProceeds": 1.0, "serialNumber": "INV-0001", "location": "text", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreCode": "CT-001", "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "monthsRemaining": 1 } ], "totalCost": 10005.0, "totalAccumulatedDepreciation": 10005.0, "totalBookValue": 10005.0, "byClass": [ { "assetClass": "text", "label": "Karoo Fresh Holdings Ltd", "count": 3, "cost": 10005.0, "accumulatedDepreciation": 1.0, "bookValue": 10005.0 } ], "periodsOutstanding": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "General ledger" ], "summary": "Capitalise an asset against a SARS BGR7 class, with the income tax allowance it is claimed under (taxAllowance), any tax value brought in, and the date it was brought into use (broughtIntoUseDate, not before the purchase; the allowance runs from it, the purchase date when blank).", "operationId": "postApiFixedAssets", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "assetClass": { "type": "string" }, "acquisitionDate": { "type": "string", "format": "date" }, "cost": { "type": "number" }, "description": { "type": "string" }, "residualValue": { "type": "number" }, "usefulLifeMonths": { "type": "integer" }, "usefulLifeReliable": { "type": "boolean" }, "method": { "type": "string" }, "ratePercent": { "type": "number" }, "serialNumber": { "type": "string" }, "location": { "type": "string" }, "costCentreId": { "type": "string" }, "supplierContactId": { "type": "string" }, "notes": { "type": "string" }, "capitalise": { "type": "boolean" }, "reclassifyFromAccountCode": { "type": "string" }, "bankAccountId": { "type": "string" }, "vatAmount": { "type": "number" }, "supplierVatNumber": { "type": "string" }, "passengerCar": { "type": "boolean" }, "clientId": { "type": "string" }, "taxAllowance": { "type": "string" }, "taxValue": { "type": "number" }, "taxValueDate": { "type": "string", "format": "date" }, "broughtIntoUseDate": { "type": "string", "format": "date" } } }, "example": { "name": "Karoo Fresh Holdings Ltd", "assetClass": "Computer equipment", "acquisitionDate": "2026-09-30", "cost": 1500.0, "description": "Consulting services — August 2026", "residualValue": 10005.0, "usefulLifeMonths": 1, "usefulLifeReliable": true, "method": "eft", "ratePercent": 15.0, "serialNumber": "INV-0001", "location": "Cape Town HQ", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "capitalise": true, "reclassifyFromAccountCode": "CT-001", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vatAmount": 225.0, "supplierVatNumber": "4082456789", "passengerCar": false, "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "taxAllowance": "s12e", "taxValue": 30000.0, "taxValueDate": "2026-02-28", "broughtIntoUseDate": "2026-03-15" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiFixedAssetsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiFixedAssetsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fixed-assets/classes": { "get": { "tags": [ "General ledger" ], "summary": "The SARS BGR7 wear-and-tear classes and their write-off periods.", "operationId": "getApiFixedAssetsClasses", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "defaultLifeMonths": { "type": "integer" }, "defaultMethod": { "type": "string" }, "depreciable": { "type": "boolean" }, "note": { "type": "string" } } } }, "example": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd", "defaultLifeMonths": 1, "defaultMethod": "eft", "depreciable": true, "note": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fixed-assets/capitalisation-policy": { "get": { "tags": [ "General ledger" ], "summary": "The company's capitalisation threshold (items under it are expensed) and SARS's R7 000 small item limit.", "operationId": "getApiFixedAssetsCapitalisationPolicy", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiFixedAssetsCapitalisationPolicyResponse" }, "example": { "threshold": 5000.0, "smallItemLimit": 7000.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "General ledger" ], "summary": "Set the company's capitalisation threshold, or clear it with null.", "operationId": "putApiFixedAssetsCapitalisationPolicy", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "threshold": { "type": "number" } } }, "example": { "threshold": 5000.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiFixedAssetsCapitalisationPolicyResponse" }, "example": { "threshold": 5000.0, "smallItemLimit": 7000.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fixed-assets/capitalisation-check": { "get": { "tags": [ "General ledger" ], "summary": "Read where a purchase is coded: does the capitalisation policy suggest another account for this amount? It suggests and never decides.", "operationId": "getApiFixedAssetsCapitalisationCheck", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "accountCode", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1140" }, { "name": "amount", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "3000" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "advice": { "type": "string" }, "suggestedAccountCode": { "type": "string" } } }, "example": { "advice": "This is under your capitalisation policy of R5000.00, so an item like it is normally expensed, not capitalised. Code it to 6050 Computer & IT Expenses instead of 1140, or lower the policy.", "suggestedAccountCode": "6050" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fixed-assets/{id}": { "get": { "tags": [ "General ledger" ], "summary": "One asset with its carrying value.", "operationId": "getApiFixedAssetsById", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiFixedAssetsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiFixedAssetsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "General ledger" ], "summary": "Update an asset.", "operationId": "putApiFixedAssetsById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "residualValue": { "type": "number" }, "usefulLifeMonths": { "type": "integer" }, "usefulLifeReliable": { "type": "boolean" }, "method": { "type": "string" }, "ratePercent": { "type": "number" }, "serialNumber": { "type": "string" }, "location": { "type": "string" }, "costCentreId": { "type": "string" }, "notes": { "type": "string" }, "taxAllowance": { "type": "string" }, "taxValue": { "type": "number" }, "taxValueDate": { "type": "string", "format": "date" }, "broughtIntoUseDate": { "type": "string", "format": "date" } } }, "example": { "name": "Toyota Hilux (CA 123-456)", "description": "Consulting services — August 2026", "residualValue": 10005.0, "usefulLifeMonths": 1, "usefulLifeReliable": true, "method": "eft", "ratePercent": 15.0, "serialNumber": "INV-0001", "location": "Cape Town HQ", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "taxAllowance": "s12e", "taxValue": 30000.0, "taxValueDate": "2026-02-28", "broughtIntoUseDate": "2026-03-15" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiFixedAssetsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiFixedAssetsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "General ledger" ], "summary": "Remove an asset that was capitalised in error.", "operationId": "deleteApiFixedAssetsById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiBillsByIdResponse" }, "example": { "ledgerNotice": "This run includes a catch-up deduction; the year-to-date total is correct." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fixed-assets/{id}/schedule": { "get": { "tags": [ "General ledger" ], "summary": "The depreciation schedule for one asset.", "operationId": "getApiFixedAssetsByIdSchedule", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "periodEnd": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "accumulatedAfter": { "type": "number" }, "bookValueAfter": { "type": "number" }, "journalId": { "type": "string" } } } }, "example": [ { "periodEnd": "2026-09-30", "amount": 10005.0, "accumulatedAfter": 1.0, "bookValueAfter": 10005.0, "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fixed-assets/depreciation/run": { "post": { "tags": [ "General ledger" ], "summary": "Post the month's depreciation across the register.", "operationId": "postApiFixedAssetsDepreciationRun", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "through", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiFixedAssetsDepreciationRunRequest" }, "example": { "period": "2026-08" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "assetsProcessed": { "type": "integer" }, "periodsPosted": { "type": "integer" }, "totalCharged": { "type": "number" }, "skipped": { "type": "array", "items": { "type": "string" } } } }, "example": { "assetsProcessed": 1, "periodsPosted": 1, "totalCharged": 10005.0, "skipped": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fixed-assets/{id}/dispose": { "post": { "tags": [ "General ledger" ], "summary": "Dispose of an asset and post the profit or loss.", "operationId": "postApiFixedAssetsByIdDispose", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disposalDate": { "type": "string", "format": "date" }, "proceeds": { "type": "number" }, "bankAccountId": { "type": "string" }, "inputTaxWasDenied": { "type": "boolean" }, "customerId": { "type": "null" } } }, "example": { "disposalDate": "2026-09-30", "proceeds": 310000.0, "bankAccountId": "7f6c1a2e-0000-4000-8000-000000000001", "inputTaxWasDenied": false, "customerId": null } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiFixedAssetsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiFixedAssetsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/summary": { "get": { "tags": [ "Reports & analytics" ], "summary": "The dashboard KPI row — cash, receivables, revenue MTD.", "operationId": "getApiReportsSummary", "description": "Requires the `dashboard:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "dashboard:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsSummaryResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReportsSummaryResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/kpi-summary": { "get": { "tags": [ "Reports & analytics" ], "summary": "The same KPI figures for the Reports screen — needs reports:view only (the dashboard's /api/reports/summary also needs dashboard:view).", "operationId": "getApiReportsKpiSummary", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsSummaryResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReportsSummaryResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/cash-forecast": { "get": { "tags": [ "Reports & analytics" ], "summary": "The cash runway ring's figures.", "operationId": "getApiReportsCashForecast", "description": "Requires the `dashboard:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "dashboard:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "How many days forward or back the window covers.", "schema": { "type": "integer" }, "example": "90" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOfLabel": { "type": "string" }, "openingBalance": { "type": "number" }, "weeks": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "inflow": { "type": "number" }, "outflow": { "type": "number" }, "balance": { "type": "number" } } } }, "statementBalance": { "type": "number" }, "unreconciledDifference": { "type": "number" }, "overdueReceivables": { "type": "number" } } }, "example": { "asOfLabel": "Karoo Fresh Holdings Ltd", "openingBalance": 10005.0, "weeks": [ { "label": "Karoo Fresh Holdings Ltd", "inflow": 1.0, "outflow": 1.0, "balance": 10005.0 } ], "statementBalance": 10005.0, "unreconciledDifference": 1.0, "overdueReceivables": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/income-statement": { "get": { "tags": [ "Reports & analytics" ], "summary": "Income statement (IFRS for SMEs).", "operationId": "getApiReportsIncomeStatement", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "compare", "in": "query", "required": false, "schema": { "type": "string" }, "example": "previous-year" }, { "name": "columns", "in": "query", "required": false, "schema": { "type": "string" }, "example": "quarter" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsIncomeStatementResponse" }, "example": { "periodLabel": "2026-09", "revenue": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "costOfSales": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "operatingExpenses": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "otherIncome": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "tax": 1305.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/balance-sheet": { "get": { "tags": [ "Reports & analytics" ], "summary": "Balance sheet at a date.", "operationId": "getApiReportsBalanceSheet", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "compare", "in": "query", "required": false, "schema": { "type": "string" }, "example": "previous-year" }, { "name": "columns", "in": "query", "required": false, "schema": { "type": "string" }, "example": "quarter" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOfLabel": { "type": "string" }, "currentAssets": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "nonCurrentAssets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "cost": { "type": "number" }, "accumulatedDepreciation": { "type": "number" } } } }, "currentLiabilities": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "nonCurrentLiabilities": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "shareCapital": { "type": "number" }, "retainedEarnings": { "type": "number" }, "currentYearProfit": { "type": "number" } } }, "example": { "asOfLabel": "Karoo Fresh Holdings Ltd", "currentAssets": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "nonCurrentAssets": [ { "name": "Karoo Fresh Holdings Ltd", "cost": 10005.0, "accumulatedDepreciation": 1.0 } ], "currentLiabilities": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "nonCurrentLiabilities": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "shareCapital": 1.0, "retainedEarnings": 1.0, "currentYearProfit": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/cash-flow": { "get": { "tags": [ "Reports & analytics" ], "summary": "Direct-method cash flow statement.", "operationId": "getApiReportsCashFlow", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "compare", "in": "query", "required": false, "schema": { "type": "string" }, "example": "previous-year" }, { "name": "columns", "in": "query", "required": false, "schema": { "type": "string" }, "example": "quarter" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "operating": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "investing": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "financing": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "cashAtStart": { "type": "number" }, "cashAtEnd": { "type": "number" } } }, "example": { "periodLabel": "2026-09", "operating": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "investing": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "financing": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "cashAtStart": 1.0, "cashAtEnd": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/report-packs": { "get": { "tags": [ "Reports & analytics" ], "summary": "Management packs: a cover, commentary and an ordered list of reports produced for one period (last_month or year_to_date).", "operationId": "getApiReportPacks", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiReportPacksResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Board pack", "coverTitle": "Monthly board pack", "commentary": "A strong month.", "reports": [ "income", "balance", "ageddebtors" ], "period": "last_month" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Reports & analytics" ], "summary": "Save a management pack. Every report must be one a schedule can send; an unknown one is refused, not dropped.", "operationId": "postApiReportPacks", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportPacksRequest" }, "example": { "name": "Board pack", "coverTitle": "Monthly board pack", "commentary": "A strong month.", "reports": [ "income", "balance", "ageddebtors" ], "period": "last_month" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportPacksResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiReportPacksResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/report-packs/{id}": { "put": { "tags": [ "Reports & analytics" ], "summary": "Change a management pack.", "operationId": "putApiReportPacksById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportPacksRequest" }, "example": { "name": "Board pack", "coverTitle": "Monthly board pack", "commentary": "A strong month.", "reports": [ "income", "balance", "ageddebtors" ], "period": "last_month" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportPacksResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiReportPacksResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Reports & analytics" ], "summary": "Remove a management pack.", "operationId": "deleteApiReportPacksById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/report-packs/{id}/pdf": { "get": { "tags": [ "Reports & analytics" ], "summary": "The pack as one PDF: the cover and commentary, then each report on its own page, built by the same code as the report on the screen. Without from and to it is the pack's own period.", "operationId": "getApiReportPacksByIdPdf", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" } ], "responses": { "200": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/favourites": { "get": { "tags": [ "Reports & analytics" ], "summary": "The signed-in user's favourite reports, in their gallery order.", "operationId": "getApiReportsFavourites", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiReportsFavouritesRequest" }, "example": { "reportIds": [ "ratios", "income" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Reports & analytics" ], "summary": "Replace the signed-in user's favourite reports, in order.", "operationId": "putApiReportsFavourites", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiReportsFavouritesRequest" }, "example": { "reportIds": [ "ratios", "income" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiReportsFavouritesRequest" }, "example": { "reportIds": [ "ratios", "income" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/recurring/{id}/lease": { "get": { "tags": [ "Reports & analytics" ], "summary": "A recurring schedule's lease terms: property (a value of an analysis dimension), unit, start, escalation and the deposit the agreement requires (what is actually held is on /deposit). The rent, tenant, cycle and end date are the schedule's. 404 when the schedule has no lease.", "operationId": "getApiRecurringByIdLease", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiRecurringByIdLeaseResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiRecurringByIdLeaseResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Reports & analytics" ], "summary": "Create or replace a schedule's lease terms. An escalation needs the date it first applies; the cycle raised on or after that date is raised at the escalated rent, and the date then moves on by escalationMonths. use is residential (the rent is raised VAT exempt) or commercial. straightLine true recognises the rent on a straight line over the term (IFRS for SMEs 20.25): the schedule must have an end date, the level rent is fixed from the cycles still to come, each rent invoice then credits income at the level rent and carries the difference to 1335 Straight-line Rent Receivable, and the last invoice clears it. It cannot be switched off once an invoice has been raised under it.", "operationId": "putApiRecurringByIdLease", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "propertyId": { "type": "string" }, "unit": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "escalationPercent": { "type": "number" }, "escalationDate": { "type": "string", "format": "date" }, "escalationMonths": { "type": "integer" }, "deposit": { "type": "number" }, "use": { "type": "string" }, "straightLine": { "type": "boolean" } } }, "example": { "propertyId": "7d0c2f4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "unit": "1A", "startDate": "2026-03-01", "escalationPercent": 8.0, "escalationDate": "2027-03-01", "escalationMonths": 12, "deposit": 20000.0, "use": "residential", "straightLine": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiRecurringByIdLeaseResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiRecurringByIdLeaseResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Reports & analytics" ], "summary": "Remove a schedule's lease terms. The schedule itself, and the invoices it has raised, are untouched.", "operationId": "deleteApiRecurringByIdLease", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rented-leases": { "get": { "tags": [ "Reports & analytics" ], "summary": "The leases the business rents (IFRS for SMEs 20.15): landlord, term, the first cycle's rent excluding VAT, its escalation, the level expense per cycle those make, and what the bills against each lease have billed, expensed and accrued so far (the accrual is account 2122 Straight-line Rent Accrual).", "operationId": "getApiRentedLeases", "description": "Requires the `expenses:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRentedLeasesResponse" } }, "example": [ { "id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "contactId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "contactName": "Karoo Properties", "description": "Head office, 12 Main Street", "startDate": "2026-03-01", "endDate": "2029-02-28", "intervalMonths": 1, "rent": 10000.0, "escalationPercent": 10.0, "escalationDate": "2027-03-01", "escalationMonths": 12, "levelRent": 11033.33, "cycles": 36, "bills": 12, "billed": 120000.0, "expensed": 132399.96, "accrued": 12399.96, "kind": "operating", "loanId": null, "fixedAssetId": null } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Reports & analytics" ], "summary": "Make a lease the business rents. Its rent expense is straight-lined over the term: a bill that names the lease (rentedLeaseId on POST/PUT /api/bills) is expensed at the level amount and the difference goes to 2122 Straight-line Rent Accrual, which the last bill clears. The term needs an end date; escalation needs the date it first applies; rent falls due every 1, 3, 6 or 12 months. 400 names what to correct.", "operationId": "postApiRentedLeases", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRentedLeasesRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRentedLeasesRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRentedLeasesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRentedLeasesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rented-leases/finance": { "post": { "tags": [ "Reports & analytics" ], "summary": "Record a lease the business holds as a FINANCE lease (IFRS for SMEs 20.9-20.12): monthly payments in arrears (or, with paymentsInAdvance, the first on startDate), the rate implicit in the lease (or the incremental borrowing rate) and the item's fair value. The asset and the obligation are recognised at the lower of the fair value and the payments' present value: the obligation is a borrowing in the loan register (its schedule splits each payment into finance charge and capital, and the balance sheet splits it current and non-current), the asset an entry in the fixed asset register depreciated over the shorter of the lease term and its useful life unless ownership is expected, and the journal DR the asset class's cost account / CR the obligation account (2020 by default). initialDirectCosts are added to the asset (20.9); a payment in advance is settled at once, so the obligation is the rest; both leave the bank account bankAccountId as its own bank leg (with none named, the company's only bank account, or the pooled 1350 when it has none; several and none named is refused), or are credited to paidFromAccountCode when it names another account. assetCost and obligation answer what was recognised. The statements note the carrying amount of the assets held under finance leases by class (20.13(a)). Code each later payment as a loan instalment. 400 names what to correct.", "operationId": "postApiRentedLeasesFinance", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "lessorName": { "type": "string" }, "description": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "payment": { "type": "number" }, "payments": { "type": "integer" }, "ratePercent": { "type": "number" }, "fairValue": { "type": "number" }, "assetClass": { "type": "string" }, "usefulLifeMonths": { "type": "integer" }, "ownershipExpected": { "type": "boolean" }, "obligationAccountCode": { "type": "string" }, "paymentsInAdvance": { "type": "boolean" }, "initialDirectCosts": { "type": "number" }, "paidFromAccountCode": { "type": "string" }, "bankAccountId": { "type": "string" } } }, "example": { "contactId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "lessorName": "WesBank", "description": "Delivery vehicle", "startDate": "2026-03-01", "payment": 5000.0, "payments": 36, "ratePercent": 12.0, "fairValue": 160000.0, "assetClass": "motor_vehicle", "usefulLifeMonths": 60, "ownershipExpected": false, "obligationAccountCode": "2020", "paymentsInAdvance": false, "initialDirectCosts": 2000.0, "paidFromAccountCode": "1350", "bankAccountId": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "loanId": { "type": "string" }, "fixedAssetId": { "type": "string" }, "assetNumber": { "type": "string" }, "description": { "type": "string" }, "lessorName": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "payment": { "type": "number" }, "payments": { "type": "integer" }, "ratePercent": { "type": "number" }, "fairValue": { "type": "number" }, "presentValue": { "type": "number" }, "carryingAmount": { "type": "number" }, "effectiveRatePercent": { "type": "number" }, "depreciationMonths": { "type": "integer" }, "obligationAccountCode": { "type": "string" }, "assetAccountCode": { "type": "string" }, "paymentsInAdvance": { "type": "boolean" }, "initialDirectCosts": { "type": "number" }, "assetCost": { "type": "number" }, "obligation": { "type": "number" } } }, "example": { "id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "loanId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fixedAssetId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "assetNumber": "FA-0007", "description": "Delivery vehicle", "lessorName": "WesBank", "startDate": "2026-03-01", "endDate": "2029-03-01", "payment": 5000.0, "payments": 36, "ratePercent": 12.0, "fairValue": 160000.0, "presentValue": 150537.53, "carryingAmount": 150537.53, "effectiveRatePercent": 12.0, "depreciationMonths": 36, "obligationAccountCode": "2020", "assetAccountCode": "1120", "paymentsInAdvance": false, "initialDirectCosts": 2000.0, "assetCost": 152537.53, "obligation": 150537.53 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rented-leases/{id}": { "put": { "tags": [ "Reports & analytics" ], "summary": "Change a lease the business rents. The landlord and description can change at any time; the term, rent and escalation cannot once a bill is against the lease (409 names the remedy: take the bills off it, or make a new lease).", "operationId": "putApiRentedLeasesById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRentedLeasesRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRentedLeasesRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRentedLeasesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRentedLeasesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Reports & analytics" ], "summary": "Remove a lease the business rents. 409 while bills are against it: its straight-line accrual would be stranded; clear the lease on each bill first.", "operationId": "deleteApiRentedLeasesById", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/recurring/{id}/lease/deposit": { "get": { "tags": [ "Reports & analytics" ], "summary": "A lease's deposit: what the agreement requires, what the lease HOLDS (taken less applied less refunded — the book that ties to account 2158 Tenant Deposits Held), and every movement.", "operationId": "getApiRecurringByIdLeaseDeposit", "description": "Requires the `invoices:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiRecurringByIdLeaseDepositResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiRecurringByIdLeaseDepositResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Reports & analytics" ], "summary": "Take the tenant's deposit: debits the bank account and credits 2158 Tenant Deposits Held (a liability, tagged with the tenant, no VAT). With interest true it records the bank's interest on the deposit account instead — the tenant's (Rental Housing Act s5(3)), booked the same way as a movement of kind interest, held and refunded with the deposit, never income. The rent roll's deposit held reads this book. A bank line cannot be coded straight to 2158.", "operationId": "postApiRecurringByIdLeaseDeposit", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" }, "bankAccountId": { "type": "string" }, "on": { "type": "string", "format": "date" }, "method": { "type": "string" }, "reference": { "type": "string" }, "interest": { "type": "boolean" } } }, "example": { "amount": 20000.0, "bankAccountId": "6e5d4c3b-2a19-4807-96f5-e4d3c2b1a098", "on": "2026-03-01", "method": "eft", "reference": "Deposit 1A", "interest": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiRecurringByIdLeaseDepositResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiRecurringByIdLeaseDepositResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/recurring/{id}/lease/deposit/apply": { "post": { "tags": [ "Reports & analytics" ], "summary": "Apply the deposit held to one of the tenant's own invoices, up to what it owes, as a payment out of 2158 (DR 2158 / CR 1320). Whatever is left stays held for a refund. 409 when the lease holds nothing or the invoice is another customer's.", "operationId": "postApiRecurringByIdLeaseDepositApply", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRecurringByIdLeaseDepositApplyRequest" }, "example": { "invoiceId": "d4c3b2a1-0f9e-4d8c-8b7a-695847362514", "on": "2026-09-30" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiRecurringByIdLeaseDepositResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiRecurringByIdLeaseDepositResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/recurring/{id}/lease/deposit/refund": { "post": { "tags": [ "Reports & analytics" ], "summary": "Pay back the deposit held — all of it, or amount — from a bank account (DR 2158 / CR bank). 409 when more than is held is asked for.", "operationId": "postApiRecurringByIdLeaseDepositRefund", "description": "Requires the `invoices:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "invoices:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRecurringByIdLeaseDepositRefundRequest" }, "example": { "bankAccountId": "6e5d4c3b-2a19-4807-96f5-e4d3c2b1a098", "on": "2026-09-30", "amount": 3000.0, "reference": "Refund 1A" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiRecurringByIdLeaseDepositResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiRecurringByIdLeaseDepositResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/rent-roll": { "get": { "tags": [ "Reports & analytics" ], "summary": "Every lease: property, unit, tenant, rent, next escalation and the rent it brings, the deposit the agreement requires and the deposit HELD (the lease's deposit book, which ties to account 2158 Tenant Deposits Held; the roll shows the ledger's 2158 and the difference), and what the tenant owes and how much of it is past due at the date — the same receivables the aged debtors report reads, per tenant. Only leases running on the date are listed; rents are totalled as monthly equivalents of base-currency leases, and the owed and arrears totals count each tenant once.", "operationId": "getApiReportsRentRoll", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-13" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "type": "string", "format": "date" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "leaseId": { "type": "string" }, "scheduleId": { "type": "string" }, "property": { "type": "string" }, "unit": { "type": "string" }, "contactId": { "type": "string" }, "tenantName": { "type": "string" }, "rent": { "type": "number" }, "frequency": { "type": "string" }, "currency": { "type": "string" }, "monthlyRent": { "type": "number" }, "active": { "type": "boolean" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "nextEscalation": { "type": "string", "format": "date" }, "nextRent": { "type": "number" }, "deposit": { "type": "number" }, "depositHeld": { "type": "number" }, "owed": { "type": "number" }, "arrears": { "type": "number" } } } }, "totalMonthlyRent": { "type": "number" }, "foreignCurrencyLeases": { "type": "integer" }, "totalDeposits": { "type": "number" }, "depositsLedgerBalance": { "type": "number" }, "depositsDifference": { "type": "number" }, "totalOwed": { "type": "number" }, "totalArrears": { "type": "number" } } }, "example": { "asOf": "2026-10-13", "rows": [ { "leaseId": "5b1e9c3a-7d2f-4e8a-9c10-2f3a4b5c6d7e", "scheduleId": "a3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e", "property": "12 Main Street", "unit": "1A", "contactId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "tenantName": "Unit Tenant", "rent": 10800.0, "frequency": "monthly", "currency": "ZAR", "monthlyRent": 10800.0, "active": true, "startDate": "2026-03-01", "endDate": "2029-02-28", "nextEscalation": "2027-03-01", "nextRent": 11664.0, "deposit": 20000.0, "depositHeld": 20000.0, "owed": 15800.0, "arrears": 5000.0 } ], "totalMonthlyRent": 10800.0, "foreignCurrencyLeases": 0, "totalDeposits": 20000.0, "depositsLedgerBalance": 20000.0, "depositsDifference": 0.0, "totalOwed": 15800.0, "totalArrears": 5000.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/funds": { "get": { "tags": [ "Reports & analytics" ], "summary": "A non-profit's funds: each value of the fund dimension with its balance brought forward, income, expenditure and balance carried forward, restricted funds marked. The figures are the departmental income statement's on that dimension; totalSurplus is checked against the income statement and reconciles says whether they agree.", "operationId": "getApiReportsFunds", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "dimension", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "2" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "dimension": { "type": "integer" }, "dimensionName": { "type": "string" }, "funds": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsFundsResponseFundsItem" } }, "totalSurplus": { "type": "number" }, "incomeStatementSurplus": { "type": "number" }, "reconciles": { "type": "boolean" }, "restrictedClosing": { "type": "number" } } }, "example": { "periodLabel": "1 March 2026 – 28 February 2027", "from": "2026-03-01", "to": "2027-02-28", "dimension": 2, "dimensionName": "Fund", "funds": [ { "fundId": "7d0c2f4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "code": "BUILD", "name": "Building fund", "restricted": true, "opening": 40000.0, "income": 25000.0, "expenditure": 18000.0, "surplus": 7000.0, "closing": 47000.0 } ], "totalSurplus": 7000.0, "incomeStatementSurplus": 7000.0, "reconciles": true, "restrictedClosing": 47000.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/funds/{fundId}": { "get": { "tags": [ "Reports & analytics" ], "summary": "The report a donor receives for one fund: its movement for the period and the income statement lines behind it.", "operationId": "getApiReportsFundsByFundId", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "fundId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "dimension", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "2" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "fund": { "$ref": "#/components/schemas/GetApiReportsFundsResponseFundsItem" }, "statement": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "revenue": { "type": "array", "items": { "type": "object" } }, "costOfSales": { "type": "array", "items": { "type": "object" } }, "operatingExpenses": { "type": "array", "items": { "type": "object" } }, "otherIncome": { "type": "array", "items": { "type": "object" } }, "tax": { "type": "number" } } } } }, "example": { "periodLabel": "1 March 2026 – 28 February 2027", "fund": { "fundId": "7d0c2f4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "code": "BUILD", "name": "Building fund", "restricted": true, "opening": 40000.0, "income": 25000.0, "expenditure": 18000.0, "surplus": 7000.0, "closing": 47000.0 }, "statement": { "periodLabel": "1 March 2026 – 28 February 2027", "revenue": [], "costOfSales": [], "operatingExpenses": [], "otherIncome": [], "tax": 0.0 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/ratios": { "get": { "tags": [ "Reports & analytics" ], "summary": "Current and quick ratio, debtor, creditor and stock days, gross and net margin for the period, at its last day. Each ratio carries the two figures it divides, read from the statement that owns them; a ratio whose denominator is zero is null rather than 0.", "operationId": "getApiReportsRatios", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "ratios": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "unit": { "type": "string" }, "value": { "type": "number" }, "numerator": { "type": "number" }, "denominator": { "type": "number" }, "formula": { "type": "string" } } } } } }, "example": { "periodLabel": "1 March 2026 – 28 February 2027", "from": "2026-03-01", "to": "2027-02-28", "days": 365, "ratios": [ { "key": "debtorDays", "label": "Debtor days", "unit": "days", "value": 41.2, "numerator": 125000.0, "denominator": 1107400.0, "formula": "Receivables ÷ credit sales × days in the period" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/trial-balance": { "get": { "tags": [ "Reports & analytics" ], "summary": "Trial balance. ?asOf= is the end of the period, the same as ?to= (send one, or both with the same date: different dates are refused). Accepts ?costCentreId=18f15bff-535b-5d77-b93c-7920ddb6e614 or the literal ?costCentreId=unallocated to restrict it to one branch, department or project; anything else is refused rather than widened to the whole company. ?compare=previous-year or previous-period adds the same trial balance over the prior range as comparative, as the statements do.", "operationId": "getApiReportsTrialBalance", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "includeZero", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" }, { "name": "compare", "in": "query", "required": false, "schema": { "type": "string" }, "example": "previous-year" }, { "name": "costCentreId", "in": "query", "required": false, "description": "Restrict to one cost centre, or the literal `unallocated`. An unparseable value is refused rather than widened to the whole company.", "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "periodLabel": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "accountType": { "type": "string" }, "openingBalance": { "type": "number" }, "debit": { "type": "number" }, "credit": { "type": "number" }, "closingBalance": { "type": "number" }, "closingDebit": { "type": "number" }, "closingCredit": { "type": "number" }, "subtype": { "type": "string" }, "isContra": { "type": "boolean" } } } }, "totalDebit": { "type": "number" }, "totalCredit": { "type": "number" }, "totalClosingDebit": { "type": "number" }, "totalClosingCredit": { "type": "number" }, "balanced": { "type": "boolean" }, "empty": { "type": "boolean" }, "comparative": { "type": "null" } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "periodLabel": "2026-09", "rows": [ { "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "accountType": "asset", "openingBalance": 10005.0, "debit": 1.0, "credit": 1.0, "closingBalance": 10005.0, "closingDebit": 1.0, "closingCredit": 1.0, "subtype": "text", "isContra": false } ], "totalDebit": 10005.0, "totalCredit": 10005.0, "totalClosingDebit": 10005.0, "totalClosingCredit": 10005.0, "balanced": true, "empty": true, "comparative": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/general-ledger": { "get": { "tags": [ "Reports & analytics" ], "summary": "General ledger detail for an account. Takes the same ?costCentreId= filter as the trial balance, brought-forward balance included.", "operationId": "getApiReportsGeneralLedger", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "costCentreId", "in": "query", "required": false, "description": "Restrict to one cost centre, or the literal `unallocated`. An unparseable value is refused rather than widened to the whole company.", "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "periodLabel": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "accountType": { "type": "string" }, "openingBalance": { "type": "number" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsDrillDownByAccountIdResponseLinesItem" } }, "totalDebit": { "type": "number" }, "totalCredit": { "type": "number" }, "closingBalance": { "type": "number" } } } }, "empty": { "type": "boolean" } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "periodLabel": "2026-09", "accounts": [ { "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "accountType": "asset", "openingBalance": 10005.0, "lines": [ { "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "journalNumber": "INV-0001", "date": "2026-09-01", "sourceType": "invoice", "sourceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "description": "Consulting services — August 2026", "contactName": "Karoo Fresh Holdings Ltd", "costCentreCode": "CT-001", "debit": 1.0, "credit": 1.0, "balance": 10005.0 } ], "totalDebit": 10005.0, "totalCredit": 10005.0, "closingBalance": 10005.0 } ], "empty": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/commissions": { "get": { "tags": [ "Reports & analytics" ], "summary": "Each salesperson's commission for a period, worked out from the lines Sales & Margin reads. Nothing is stored but the rate.", "operationId": "getApiReportsCommissions", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-31" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "ratePercent": { "type": "number" }, "basis": { "type": "string" }, "earnedOn": { "type": "string" }, "revenue": { "type": "number" }, "margin": { "type": "number" }, "commissionable": { "type": "number" }, "commission": { "type": "number" }, "employeeId": { "type": "string" } } } }, "totalCommission": { "type": "number" } } }, "example": { "periodLabel": "1 October 2026 – 31 October 2026", "rows": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Thandi Nkosi", "ratePercent": 5.0, "basis": "margin", "earnedOn": "issued", "revenue": 18000.0, "margin": 9000.0, "commissionable": 9000.0, "commission": 450.0, "employeeId": "7c2e9b14-0d3a-4f6e-8b21-5a9c1d7e3f40" } ], "totalCommission": 450.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/commissions/rates": { "put": { "tags": [ "Reports & analytics" ], "summary": "Set a salesperson's rate, on revenue or margin, earned when a document is issued or as it is paid.", "operationId": "putApiReportsCommissionsRates", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "ratePercent": { "type": "number" }, "basis": { "type": "string" }, "earnedOn": { "type": "string" } } }, "example": { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ratePercent": 5.0, "basis": "margin", "earnedOn": "issued" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/commissions/to-payroll": { "post": { "tags": [ "Reports & analytics" ], "summary": "Put each person's commission for the dates on their payslip for the period. Sending again replaces it; anyone not on the payroll is named.", "operationId": "postApiReportsCommissionsToPayroll", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "periodId": { "type": "string" } } }, "example": { "from": "2026-10-01", "to": "2026-10-31", "periodId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "integer" }, "total": { "type": "number" }, "skipped": { "type": "array", "items": { "type": "object" } } } }, "example": { "sent": 1, "total": 450.0, "skipped": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/sales-analysis": { "get": { "tags": [ "Reports & analytics" ], "summary": "Sales by item, customer or salesperson (`by=item|customer|rep`), with quantity, revenue, cost of sales and realised margin, read from invoice lines net of credit notes, with the cost each line consumed from stock. A line coded to an account the income statement puts outside revenue (Sundry Income, say) is other income, not a sale, and is left out. The totals are compared with the income statement for the same period and the response says whether they reconcile.", "operationId": "getApiReportsSalesAnalysis", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "item" }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Retail" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "by": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "quantity": { "type": "number" }, "revenue": { "type": "number" }, "costOfSales": { "type": "number" }, "margin": { "type": "number" }, "marginPct": { "type": "number" } } } }, "totalQuantity": { "type": "number" }, "totalRevenue": { "type": "number" }, "totalCostOfSales": { "type": "number" }, "totalMargin": { "type": "number" }, "incomeStatementRevenue": { "type": "number" }, "ledgerCostOfGoodsSold": { "type": "number" }, "revenueDifference": { "type": "number" }, "costOfSalesDifference": { "type": "number" }, "reconciles": { "type": "boolean" } } }, "example": { "periodLabel": "1 March 2026 – 28 February 2027", "by": "item", "rows": [ { "key": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Hiking boots", "quantity": 12.0, "revenue": 18000.0, "costOfSales": 10800.0, "margin": 7200.0, "marginPct": 40.0 } ], "totalQuantity": 12.0, "totalRevenue": 18000.0, "totalCostOfSales": 10800.0, "totalMargin": 7200.0, "incomeStatementRevenue": 18000.0, "ledgerCostOfGoodsSold": 10800.0, "revenueDifference": 0.0, "costOfSalesDifference": 0.0, "reconciles": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/purchase-analysis": { "get": { "tags": [ "Reports & analytics" ], "summary": "Purchases by item or supplier (`by=item|supplier`), from bill lines, VAT-exclusive and in the base currency.", "operationId": "getApiReportsPurchaseAnalysis", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "by", "in": "query", "required": false, "schema": { "type": "string" }, "example": "supplier" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "by": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "quantity": { "type": "number" }, "amount": { "type": "number" } } } }, "totalAmount": { "type": "number" } } }, "example": { "periodLabel": "1 March 2026 – 28 February 2027", "by": "supplier", "rows": [ { "key": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "quantity": 40.0, "amount": 24000.0 } ], "totalAmount": 24000.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/income-by-cost-centre": { "get": { "tags": [ "Reports & analytics" ], "summary": "The income statement with one column per cost centre — the departmental or branch P&L, for one legal entity with several branches. Every column and the total come from one read of journal_lines through the one income-statement classifier, and the response says whether the columns reconcile to the company total rather than leaving the reader to add them up.", "operationId": "getApiReportsIncomeByCostCentre", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "dimension", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "costCentreId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "isActive": { "type": "boolean" }, "statement": { "$ref": "#/components/schemas/GetApiReportsIncomeStatementResponse" }, "netProfit": { "type": "number" } } } }, "total": { "$ref": "#/components/schemas/GetApiReportsIncomeStatementResponse" }, "totalNetProfit": { "type": "number" }, "reconciliationDifference": { "type": "number" }, "reconciles": { "type": "boolean" }, "unconfigured": { "type": "boolean" } } }, "example": { "periodLabel": "2026-09", "from": "2026-09-01", "to": "2026-09-30", "columns": [ { "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "kind": "standard", "isActive": true, "statement": { "periodLabel": "2026-09", "revenue": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "costOfSales": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "operatingExpenses": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "otherIncome": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "tax": 1305.0 }, "netProfit": 8700.0 } ], "total": { "periodLabel": "2026-09", "revenue": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "costOfSales": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "operatingExpenses": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "otherIncome": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "tax": 1305.0 }, "totalNetProfit": 8700.0, "reconciliationDifference": 1.0, "reconciles": true, "unconfigured": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/drill-down/{accountId}": { "get": { "tags": [ "Reports & analytics" ], "summary": "The transactions behind a figure, for click-through from a chart.", "operationId": "getApiReportsDrillDownByAccountId", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsDrillDownByAccountIdResponseLinesItem" } }, "totalDebit": { "type": "number" }, "totalCredit": { "type": "number" }, "net": { "type": "number" } } }, "example": { "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "from": "2026-09-01", "to": "2026-09-30", "lines": [ { "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "journalNumber": "INV-0001", "date": "2026-09-01", "sourceType": "invoice", "sourceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "description": "Consulting services — August 2026", "contactName": "Karoo Fresh Holdings Ltd", "costCentreCode": "CT-001", "debit": 1.0, "credit": 1.0, "balance": 10005.0 } ], "totalDebit": 10005.0, "totalCredit": 10005.0, "net": 8700.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/aged-debtors": { "get": { "tags": [ "Reports & analytics" ], "summary": "Aged debtors with the per-bucket breakdown the chart draws.", "operationId": "getApiReportsAgedDebtors", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsAgedDebtorsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReportsAgedDebtorsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/aged-creditors": { "get": { "tags": [ "Reports & analytics" ], "summary": "Aged creditors.", "operationId": "getApiReportsAgedCreditors", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsAgedDebtorsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReportsAgedDebtorsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/budget-vs-actual": { "get": { "tags": [ "Reports & analytics" ], "summary": "Budget against actual with variance.", "operationId": "getApiReportsBudgetVsActual", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "description": "Which of a return's periods this is. Refused rather than defaulted.", "schema": { "type": "string" }, "example": "2026-08" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "budget": { "type": "number" }, "actual": { "type": "number" } } } } } }, "example": { "periodLabel": "2026-09", "categories": [ { "category": "Office supplies", "budget": 1.0, "actual": 1.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/audit-trail/records/{type}/{id}": { "get": { "tags": [ "Reports & analytics" ], "summary": "One document's history, newest first: who created, changed, sent, voided or paid it, and what changed. type is invoice (quotes and credit notes included), bill or journal. Gated by the document's own permission (invoices:view, expenses:view, reports:view for a journal); a document in another business, or in a company the caller cannot reach, is a 404.", "operationId": "getApiAuditTrailRecordsByTypeById", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsAuditTrailResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReportsAuditTrailResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/audit-trail": { "get": { "tags": [ "Reports & analytics" ], "summary": "Who changed what in the books, and when: every audit row about invoices, bills, journals, periods, bank lines, stock, assets and contacts, newest first. Never sign-ins, roles, keys or payroll, and no IP address or browser. Needs reports:view; a person confined to some companies of a group is refused, because the trail is the whole organisation's. from and to are South African days, both inclusive. Add format=csv for every matching row as a sheet. The `actor` filter takes a user id or the email address a person signs in with (an email nobody in the business has shows no rows).", "operationId": "getApiReportsAuditTrail", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "actor", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "resourceType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "invoice" }, { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsAuditTrailResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReportsAuditTrailResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/audit-trail/people": { "get": { "tags": [ "Reports & analytics" ], "summary": "Who the books audit trail has rows for, by name and email, so a screen can offer a person filter that is a list and not a user id. A visiting accountant is listed like anyone else. The `userId` is what `actor` takes. Needs reports:view.", "operationId": "getApiReportsAuditTrailPeople", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "people": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } } } } }, "example": { "people": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Anele Dlamini", "email": "anele@practice.example" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/vat-audit": { "get": { "tags": [ "Reports & analytics" ], "summary": "The VAT201's support pack: every document behind each field — the invoices and credit notes in fields 1, 2 and 4, the bills and expense claims in field 15 — with its value and VAT, and each field's total, which is the return's. Add format=csv for the file a SARS verification asks for.", "operationId": "getApiReportsVatAudit", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-07-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-31" }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "category": { "type": "string" }, "source": { "type": "string" }, "documentId": { "type": "string" }, "reference": { "type": "string" }, "date": { "type": "string", "format": "date" }, "counterparty": { "type": "string" }, "value": { "type": "number" }, "vat": { "type": "number" } } } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "documents": { "type": "integer" } } } }, "totalOutputVat": { "type": "number" }, "totalInputVat": { "type": "number" } } }, "example": { "periodLabel": "1 July 2026 – 31 August 2026", "rows": [ { "field": "1 / 4", "category": "standard", "source": "sale", "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-2026-0042 (invoice)", "date": "2026-07-14", "counterparty": "Karoo Fresh Holdings Ltd", "value": 10000.0, "vat": 1500.0 } ], "fields": [ { "code": "1", "label": "Standard-rated supplies, including VAT", "amount": 11500.0, "documents": 1 }, { "code": "4", "label": "Output tax", "amount": 1500.0, "documents": 1 } ], "totalOutputVat": 1500.0, "totalInputVat": 0.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/vat-analysis": { "get": { "tags": [ "Reports & analytics" ], "summary": "VAT by rate and by account, which is what a VAT201 is reconciled against.", "operationId": "getApiReportsVatAnalysis", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-07-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-31" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "periods": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "standardRatedSales": { "type": "number" }, "zeroRatedSales": { "type": "number" }, "outputVat": { "type": "number" }, "inputVat": { "type": "number" }, "netVat": { "type": "number" } } } }, "totalOutputVat": { "type": "number" }, "totalInputVat": { "type": "number" }, "totalNetVat": { "type": "number" } } }, "example": { "periodLabel": "2026-09", "periods": [ { "month": "2026-09", "standardRatedSales": 1.0, "zeroRatedSales": 1.0, "outputVat": 1305.0, "inputVat": 1305.0, "netVat": 1305.0 } ], "totalOutputVat": 1305.0, "totalInputVat": 1305.0, "totalNetVat": 1305.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/bbbee": { "get": { "tags": [ "Reports & analytics" ], "summary": "The B-BBEE scorecard — six elements and the resulting level.", "operationId": "getApiReportsBbbee", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsBbbeeResponse" }, "example": { "level": 1, "totalScored": 1, "totalMax": 1, "recognitionPct": 1, "elements": [ { "element": "text", "maxPoints": 1, "scored": 1, "pct": 1 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Reports & analytics" ], "summary": "Record the inputs the scorecard cannot derive from the books.", "operationId": "putApiReportsBbbee", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "elements": { "type": "array", "items": { "type": "object", "properties": { "element": { "type": "string" }, "score": { "type": "integer" } } } } } }, "example": { "elements": [ { "element": "ownership", "score": 18 }, { "element": "skills_development", "score": 11 } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsBbbeeResponse" }, "example": { "level": 1, "totalScored": 1, "totalMax": 1, "recognitionPct": 1, "elements": [ { "element": "text", "maxPoints": 1, "scored": 1, "pct": 1 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/scheduled": { "get": { "tags": [ "Reports & analytics" ], "summary": "Scheduled report subscriptions.", "operationId": "getApiReportsScheduled", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiReportsScheduledResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "reportType": "income", "frequency": "monthly", "nextRun": "text", "recipients": "text", "format": "CSV", "active": true, "lastRun": "text", "lastStatus": "text" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Reports & analytics" ], "summary": "Schedule a report.", "operationId": "postApiReportsScheduled", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "reportType": { "type": "string" }, "frequency": { "type": "string" }, "nextRun": { "type": "string", "format": "date" }, "recipients": { "type": "string" }, "format": { "type": "string" }, "active": { "type": "boolean" }, "clientId": { "type": "string" }, "customReportId": { "type": "null" }, "packId": { "type": "null" } } }, "example": { "name": "Monthly management pack", "reportType": "income", "frequency": "monthly", "nextRun": "2026-09-01", "recipients": "finance@karoofresh.example", "format": "pdf", "active": true, "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "customReportId": null, "packId": null } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportsScheduledResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiReportsScheduledResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/scheduled/{id}": { "put": { "tags": [ "Reports & analytics" ], "summary": "Change or pause a schedule.", "operationId": "putApiReportsScheduledById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "reportType": { "type": "string" }, "frequency": { "type": "string" }, "nextRun": { "type": "string", "format": "date" }, "recipients": { "type": "string" }, "format": { "type": "string" }, "active": { "type": "boolean" } } }, "example": { "name": "Karoo Fresh Holdings Ltd", "reportType": "income", "frequency": "monthly", "nextRun": "2026-10-01", "recipients": "finance@karoofresh.example", "format": "CSV", "active": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportsScheduledResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiReportsScheduledResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Reports & analytics" ], "summary": "Remove a schedule.", "operationId": "deleteApiReportsScheduledById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/break-even": { "get": { "tags": [ "Reports & analytics" ], "summary": "Break-even analysis for the period, read off the income statement: revenue, costs split into fixed and variable, contribution margin, break-even revenue and margin of safety. Every counted account is listed with whether its behaviour was stated or is its section default (cost of sales variable, operating expenses fixed). Other income and tax are left out; the split ties back to the statement's cost of sales and operating expenses.", "operationId": "getApiReportsBreakEven", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsBreakEvenResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReportsBreakEvenResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/break-even/cost-behaviour": { "put": { "tags": [ "Reports & analytics" ], "summary": "State whether one cost-of-sales or expense account is fixed or variable for break-even, or send null to return it to its section default. Answers the recomputed analysis for the period in the query. An unknown behaviour, or an account that is not a cost, is refused.", "operationId": "putApiReportsBreakEvenCostBehaviour", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "behaviour": { "type": "string" } } }, "example": { "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "behaviour": "variable" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsBreakEvenResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReportsBreakEvenResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/custom": { "get": { "tags": [ "Reports & analytics" ], "summary": "The tenant's saved custom reports — each a definition (period grouping, dimensions, measures, filters), never a stored result.", "operationId": "getApiReportsCustom", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiReportsCustomResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "definition": { "name": "Karoo Fresh Holdings Ltd", "periodGrouping": "2026-09", "dimensions": [ "text" ], "measures": [ "text" ], "filters": { "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "sections": [ "text" ] } }, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Reports & analytics" ], "summary": "Save a custom report definition. An unknown grouping, figure or filter is refused by name rather than dropped, and a name already in use (ignoring case) answers 409.", "operationId": "postApiReportsCustom", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportsCustomRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiReportsCustomRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportsCustomResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiReportsCustomResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/custom/{id}": { "put": { "tags": [ "Reports & analytics" ], "summary": "Change a saved custom report's definition or name.", "operationId": "putApiReportsCustomById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportsCustomRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiReportsCustomRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportsCustomResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiReportsCustomResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Reports & analytics" ], "summary": "Remove a saved custom report.", "operationId": "deleteApiReportsCustomById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/custom/run": { "post": { "tags": [ "Reports & analytics" ], "summary": "Run a custom report definition without saving it. Every row is the income statement for its slice of the ledger, the totals are the income statement for the whole slice, and reconciles says whether the rows add up to them.", "operationId": "postApiReportsCustomRun", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportsCustomRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiReportsCustomRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportsCustomRunResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiReportsCustomRunResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/custom/{id}/run": { "get": { "tags": [ "Reports & analytics" ], "summary": "Re-run a saved custom report against the ledger as it stands.", "operationId": "getApiReportsCustomByIdRun", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiReportsCustomRunResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiReportsCustomRunResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/tax-pack/contents": { "get": { "tags": [ "Reports & analytics" ], "summary": "What the annual tax pack for the financial year ending in `year` will contain, and — for every file left out — why: a return your plan does not include, one your role may not read, a period that has not ended, or a company that is not a VAT vendor or employer. Ledgr prepares these files and never submits them to SARS.", "operationId": "getApiReportsTaxPackContents", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2026" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "entityName": { "type": "string" }, "yearEnd": { "type": "integer" }, "yearLabel": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "items": { "type": "array", "items": { "type": "object", "properties": { "fileName": { "type": "string" }, "title": { "type": "string" }, "included": { "type": "boolean" }, "omittedBecause": { "type": "string" } } } }, "notice": { "type": "string" } } }, "example": { "entityName": "Karoo Fresh Holdings Ltd", "yearEnd": 1, "yearLabel": "Karoo Fresh Holdings Ltd", "from": "2026-09-01", "to": "2026-09-30", "items": [ { "fileName": "SignedPO-4417.pdf", "title": "Karoo Fresh Holdings Ltd", "included": true, "omittedBecause": "text" } ], "notice": "This run includes a catch-up deduction; the year-to-date total is correct." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/tax-pack": { "get": { "tags": [ "Reports & analytics" ], "summary": "The annual tax pack as one zip: the trial balance, income statement and balance sheet, the fixed-asset register, the year's VAT201s, EMP201s and EMP501 where they apply, and the ITR14 working with its supporting trial balance, plus a README listing everything left out and why. A return with a blocking issue is left out and named, never emitted. Prepare-and-download only.", "operationId": "getApiReportsTaxPack", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2026" } ], "responses": { "200": { "description": "A file download.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/afs": { "get": { "tags": [ "Reports & analytics" ], "summary": "The annual financial statement set — cover page, responsibility statement, four statements with comparatives and disclosure-driven notes.", "operationId": "getApiReportsAfs", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "object", "properties": { "name": { "type": "string" }, "tradingAs": { "type": "string" }, "registrationNumber": { "type": "string" }, "incomeTaxNumber": { "type": "string" }, "vatNumber": { "type": "string" }, "companyType": { "type": "string" }, "address": { "type": "string" }, "natureOfBusiness": { "type": "string" }, "countryOfIncorporation": { "type": "string" }, "presentationCurrency": { "type": "string" } } }, "yearStart": { "type": "string", "format": "date" }, "yearEnd": { "type": "string", "format": "date" }, "priorYearStart": { "type": "string", "format": "date" }, "priorYearEnd": { "type": "string", "format": "date" }, "currentColumnLabel": { "type": "string" }, "priorColumnLabel": { "type": "string" }, "presentationCurrency": { "type": "string" }, "rounding": { "type": "string" }, "roundingNote": { "type": "string" }, "hasComparatives": { "type": "boolean" }, "consolidated": { "type": "boolean" }, "cover": { "type": "object", "properties": { "entityName": { "type": "string" }, "entityDescriptor": { "type": "string" }, "registrationLine": { "type": "string" }, "title": { "type": "string" }, "periodLine": { "type": "string" }, "preparationLine": { "type": "string" }, "assuranceLine": { "type": "string" }, "currencyLine": { "type": "string" }, "contentsEntries": { "type": "array", "items": { "type": "string" } } } }, "narrative": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "paragraphs": { "type": "array", "items": { "type": "string" } }, "requiresCompletion": { "type": "boolean" }, "signatureLabels": { "type": "array", "items": { "type": "string" } } } } }, "financialPosition": { "$ref": "#/components/schemas/GetApiReportsAfsResponseCashFlows" }, "profitOrLoss": { "$ref": "#/components/schemas/GetApiReportsAfsResponseCashFlows" }, "changesInEquity": { "type": "object", "properties": { "title": { "type": "string" }, "subtitle": { "type": "string" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "amounts": { "type": "array", "items": { "type": "integer" } }, "kind": { "type": "string" } } } } } }, "cashFlows": { "$ref": "#/components/schemas/GetApiReportsAfsResponseCashFlows" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "number": { "type": "integer" }, "title": { "type": "string" }, "paragraphs": { "type": "array", "items": { "type": "string" } }, "tables": { "type": "array", "items": { "type": "object", "properties": { "labelHeading": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "values": { "type": "array", "items": { "type": "object" } }, "texts": { "type": "array", "items": { "type": "object" } }, "kind": { "type": "string" }, "indent": { "type": "integer" } } } }, "numeric": { "type": "boolean" } } } }, "standardReference": { "type": "string" } } } }, "leadSchedules": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsAfsLeadSchedulesResponseItem" } }, "compliance": { "type": "object", "properties": { "entityType": { "type": "string" }, "entityTypeLabel": { "type": "string" }, "governingStatute": { "type": "string" }, "publicInterestScore": { "type": "integer" }, "pisComponents": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "points": { "type": "integer" }, "basis": { "type": "string" }, "supplied": { "type": "boolean" } } } }, "assuranceRequirement": { "type": "string" }, "assuranceLabel": { "type": "string" }, "assuranceReason": { "type": "string" }, "assuranceOverridden": { "type": "boolean" }, "financialReportingStandard": { "type": "string" }, "governingBodyTerm": { "type": "string" }, "governingBodyTermSingular": { "type": "string" }, "responsibilityStatementTitle": { "type": "string" }, "governingBodyReportTitle": { "type": "string" }, "equityCaptionShareCapital": { "type": "string" }, "equityCaptionRetained": { "type": "string" }, "entityDisclosureNotes": { "type": "array", "items": { "type": "string" } } } }, "issues": { "type": "array", "items": { "type": "object" } } } }, "example": { "entity": { "name": "Karoo Fresh Holdings Ltd", "tradingAs": "text", "registrationNumber": "2021/123456/07", "incomeTaxNumber": "INV-0001", "vatNumber": "4123456789", "companyType": "standard", "address": "12 Long Street, Cape Town, 8001", "natureOfBusiness": "Karoo Fresh Holdings Ltd", "countryOfIncorporation": "text", "presentationCurrency": "ZAR" }, "yearStart": "2026-09-01", "yearEnd": "2026-09-30", "priorYearStart": "2026-09-01", "priorYearEnd": "2026-09-30", "currentColumnLabel": "Overtime", "priorColumnLabel": "Overtime", "presentationCurrency": "ZAR", "rounding": "text", "roundingNote": "Budget deferred to the next financial year.", "hasComparatives": true, "consolidated": true, "cover": { "entityName": "Karoo Fresh Holdings Ltd", "entityDescriptor": "text", "registrationLine": "text", "title": "Karoo Fresh Holdings Ltd", "periodLine": "2026-09", "preparationLine": "text", "assuranceLine": "text", "currencyLine": "text", "contentsEntries": [ "text" ] }, "narrative": [ { "key": "text", "title": "Karoo Fresh Holdings Ltd", "paragraphs": [ "text" ], "requiresCompletion": false, "signatureLabels": [ "Karoo Fresh Holdings Ltd" ] } ], "financialPosition": { "key": "sofp", "title": "Karoo Fresh Holdings Ltd", "subtitle": "text", "lines": [ { "label": "Karoo Fresh Holdings Ltd", "currentUnits": 1, "priorUnits": 1, "noteRef": 1, "kind": "DETAIL", "indent": 1, "accountCodes": [ "CT-001" ] } ] }, "profitOrLoss": { "key": "sofp", "title": "Karoo Fresh Holdings Ltd", "subtitle": "text", "lines": [ { "label": "Karoo Fresh Holdings Ltd", "currentUnits": 1, "priorUnits": 1, "noteRef": 1, "kind": "DETAIL", "indent": 1, "accountCodes": [ "CT-001" ] } ] }, "changesInEquity": { "title": "Karoo Fresh Holdings Ltd", "subtitle": "text", "columns": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd" } ], "rows": [ { "label": "Karoo Fresh Holdings Ltd", "amounts": [ 1 ], "kind": "DETAIL" } ] }, "cashFlows": { "key": "sofp", "title": "Karoo Fresh Holdings Ltd", "subtitle": "text", "lines": [ { "label": "Karoo Fresh Holdings Ltd", "currentUnits": 1, "priorUnits": 1, "noteRef": 1, "kind": "DETAIL", "indent": 1, "accountCodes": [ "CT-001" ] } ] }, "notes": [ { "key": "text", "number": 1, "title": "Karoo Fresh Holdings Ltd", "paragraphs": [ "text" ], "tables": [ { "labelHeading": "text", "columns": [ "text" ], "rows": [ { "label": "Karoo Fresh Holdings Ltd", "values": [], "texts": [], "kind": "DETAIL", "indent": 1 } ], "numeric": true } ], "standardReference": "INV-0001" } ], "leadSchedules": [ { "statementKey": "text", "lineLabel": "Karoo Fresh Holdings Ltd", "currentUnits": 1, "priorUnits": 1, "accounts": [ { "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "accountType": "asset", "currentUnits": 1, "priorUnits": 1 } ], "ties": true } ], "compliance": { "entityType": "invoice", "entityTypeLabel": "Karoo Fresh Holdings Ltd", "governingStatute": "text", "publicInterestScore": 1, "pisComponents": [ { "label": "Karoo Fresh Holdings Ltd", "points": 1, "basis": "invoice", "supplied": false } ], "assuranceRequirement": "audit", "assuranceLabel": "Karoo Fresh Holdings Ltd", "assuranceReason": "Budget deferred to the next financial year.", "assuranceOverridden": true, "financialReportingStandard": "text", "governingBodyTerm": "directors", "governingBodyTermSingular": "text", "responsibilityStatementTitle": "Karoo Fresh Holdings Ltd", "governingBodyReportTitle": "Karoo Fresh Holdings Ltd", "equityCaptionShareCapital": "text", "equityCaptionRetained": "text", "entityDisclosureNotes": [ "Budget deferred to the next financial year." ] }, "issues": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/afs/years": { "get": { "tags": [ "Reports & analytics" ], "summary": "Which years an AFS set can be produced for.", "operationId": "getApiReportsAfsYears", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "fiscalYearEndMonth": { "type": "integer" }, "defaultYearEnd": { "type": "string", "format": "date" }, "years": { "type": "array", "items": { "type": "object", "properties": { "yearEnd": { "type": "string", "format": "date" }, "yearStart": { "type": "string", "format": "date" }, "label": { "type": "string" }, "hasComparatives": { "type": "boolean" } } } } } }, "example": { "fiscalYearEndMonth": 9, "defaultYearEnd": "2026-09-30", "years": [ { "yearEnd": "2026-09-30", "yearStart": "2026-09-01", "label": "Karoo Fresh Holdings Ltd", "hasComparatives": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/afs/settings": { "get": { "tags": [ "Reports & analytics" ], "summary": "AFS presentation settings and the Companies Act public interest score inputs.", "operationId": "getApiReportsAfsSettings", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "yearEnd", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsAfsSettingsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "financialYearEnd": "2026-09-30", "consolidated": false, "status": "sent", "rounding": "text", "preparedBy": "text", "preparedByCapacity": "text", "approvedOn": "2026-09-01", "governingBodyMembers": [ "text" ], "practitionerName": "Karoo Fresh Holdings Ltd", "practitionerFirm": "text", "assuranceEngagement": "text", "natureOfBusiness": "Karoo Fresh Holdings Ltd", "goingConcernNote": "Budget deferred to the next financial year.", "subsequentEventsNote": "Budget deferred to the next financial year.", "ownersLoanTerms": "text", "provisionsNote": "Warranty claims are settled within 12 months of sale; long-service awards after five years of service.", "contingenciesNote": "Guarantee of R500 000 given to the bank for a related company; no outflow is expected.", "noContingentLiabilities": false, "averageEmployees": 1, "beneficialInterestHolders": 1, "internallyCompiled": true, "ownerManaged": false, "publicCompany": false, "fiduciaryAssetsOverThreshold": false, "priorPeriodErrors": [ { "journalNumber": "JNL-0042", "nature": "The audit fee for the prior year was not accrued.", "occurredIn": "prior_year", "profitAccountCode": "6010" } ], "locked": false, "approvedAt": "2026-09-01T08:00:00Z", "approvedBy": "Thandi Mokoena", "figuresHash": "3f1a7c925b640d4e9a112c7e8b4f6a033f1a7c925b640d4e9a112c7e8b4f6a03", "history": [ { "approvedOn": "2026-09-01", "approvedAt": "2026-09-01T08:00:00Z", "approvedBy": "Thandi Mokoena", "figuresHash": "3f1a7c925b640d4e9a112c7e8b4f6a033f1a7c925b640d4e9a112c7e8b4f6a03", "reopenedAt": "2026-09-14T08:00:00Z", "reopenedBy": "Thandi Mokoena", "reopenReason": "A June accrual was left out" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Reports & analytics" ], "summary": "Change the AFS settings. Status final (reports:approve) approves the set: it locks the year, stores the approved figures, and takes no further edit. Status draft with a reopenReason reopens the year and records who and why.", "operationId": "putApiReportsAfsSettings", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "yearEnd", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "rounding": { "type": "string" }, "preparedBy": { "type": "string" }, "preparedByCapacity": { "type": "string" }, "approvedOn": { "type": "string", "format": "date" }, "governingBodyMembers": { "type": "array", "items": { "type": "string" } }, "practitionerName": { "type": "string" }, "practitionerFirm": { "type": "string" }, "assuranceEngagement": { "type": "string" }, "natureOfBusiness": { "type": "string" }, "goingConcernNote": { "type": "string" }, "subsequentEventsNote": { "type": "string" }, "ownersLoanTerms": { "type": "string" }, "provisionsNote": { "type": "string" }, "contingenciesNote": { "type": "string" }, "noContingentLiabilities": { "type": "boolean" }, "averageEmployees": { "type": "integer" }, "beneficialInterestHolders": { "type": "integer" }, "internallyCompiled": { "type": "boolean" }, "ownerManaged": { "type": "boolean" }, "publicCompany": { "type": "boolean" }, "fiduciaryAssetsOverThreshold": { "type": "boolean" }, "priorPeriodErrors": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiReportsAfsSettingsRequestPriorPeriodErrorsItem" } }, "reopenReason": { "type": "string" } } }, "example": { "status": "sent", "rounding": "rand", "preparedBy": "Mokoena & Co", "preparedByCapacity": "Accounting officer", "approvedOn": "2026-09-01", "governingBodyMembers": [ "Thandi Mokoena" ], "practitionerName": "Karoo Fresh Holdings Ltd", "practitionerFirm": "Mokoena & Partners Inc.", "assuranceEngagement": "Independent review", "natureOfBusiness": "Karoo Fresh Holdings Ltd", "goingConcernNote": "Budget deferred to the next financial year.", "subsequentEventsNote": "Budget deferred to the next financial year.", "ownersLoanTerms": "Unsecured; interest at the SARS official rate; repayable on 90 days' notice.", "provisionsNote": "Warranty claims are settled within 12 months of sale; long-service awards after five years of service.", "contingenciesNote": "Guarantee of R500 000 given to the bank for a related company; no outflow is expected.", "noContingentLiabilities": false, "averageEmployees": 1, "beneficialInterestHolders": 1, "internallyCompiled": true, "ownerManaged": true, "publicCompany": false, "fiduciaryAssetsOverThreshold": false, "priorPeriodErrors": [ { "journalNumber": "JNL-0042", "nature": "The audit fee for the prior year was not accrued.", "occurredIn": "prior_year", "profitAccountCode": "6010" } ], "reopenReason": "A June accrual was left out" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsAfsSettingsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "financialYearEnd": "2026-09-30", "consolidated": false, "status": "sent", "rounding": "text", "preparedBy": "text", "preparedByCapacity": "text", "approvedOn": "2026-09-01", "governingBodyMembers": [ "text" ], "practitionerName": "Karoo Fresh Holdings Ltd", "practitionerFirm": "text", "assuranceEngagement": "text", "natureOfBusiness": "Karoo Fresh Holdings Ltd", "goingConcernNote": "Budget deferred to the next financial year.", "subsequentEventsNote": "Budget deferred to the next financial year.", "ownersLoanTerms": "Unsecured; interest at the SARS official rate; repayable on 90 days' notice.", "provisionsNote": "Warranty claims are settled within 12 months of sale; long-service awards after five years of service.", "contingenciesNote": "Guarantee of R500 000 given to the bank for a related company; no outflow is expected.", "noContingentLiabilities": false, "averageEmployees": 1, "beneficialInterestHolders": 1, "internallyCompiled": true, "ownerManaged": false, "publicCompany": false, "fiduciaryAssetsOverThreshold": false, "priorPeriodErrors": [ { "journalNumber": "JNL-0042", "nature": "The audit fee for the prior year was not accrued.", "occurredIn": "prior_year", "profitAccountCode": "6010" } ], "locked": false, "approvedAt": "2026-09-01T08:00:00Z", "approvedBy": "Thandi Mokoena", "figuresHash": "3f1a7c925b640d4e9a112c7e8b4f6a033f1a7c925b640d4e9a112c7e8b4f6a03", "history": [ { "approvedOn": "2026-09-01", "approvedAt": "2026-09-01T08:00:00Z", "approvedBy": "Thandi Mokoena", "figuresHash": "3f1a7c925b640d4e9a112c7e8b4f6a033f1a7c925b640d4e9a112c7e8b4f6a03", "reopenedAt": "2026-09-14T08:00:00Z", "reopenedBy": "Thandi Mokoena", "reopenReason": "A June accrual was left out" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/reports/afs/lead-schedules": { "get": { "tags": [ "Reports & analytics" ], "summary": "The lead schedules behind each statement line. An account the preparer moved to this line (PUT /api/accounts/{id} statementClass) carries overridden: true.", "operationId": "getApiReportsAfsLeadSchedules", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsAfsLeadSchedulesResponseItem" } }, "example": [ { "statementKey": "text", "lineLabel": "Karoo Fresh Holdings Ltd", "currentUnits": 1, "priorUnits": 1, "accounts": [ { "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "accountType": "asset", "currentUnits": 1, "priorUnits": 1 } ], "ties": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/report-tables": { "get": { "tags": [ "Reports & analytics" ], "summary": "The flat, refreshable tables Excel can bind to. Accepts an API KEY directly as well as a JWT, because Power Query cannot run a token exchange and a monthly refresh cannot hold an hourly token.", "operationId": "getApiReportTables", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/report-tables/{report}": { "get": { "tags": [ "Reports & analytics" ], "summary": "One table as JSON or CSV. Read-only, scope- and licence-checked explicitly.", "operationId": "getApiReportTablesByReport", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "report", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "csv" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/overview": { "get": { "tags": [ "SARS returns" ], "summary": "Per-tax-type filing state — last filed and next due.", "operationId": "getApiSarsOverview", "description": "Requires the `vat-returns:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "isvConfigured": { "type": "boolean" }, "entityName": { "type": "string" }, "vatNumber": { "type": "string" }, "vatRegistered": { "type": "boolean" }, "vatCategory": { "type": "string" }, "vatCategoryLabel": { "type": "string" }, "vatCategoryAssumed": { "type": "boolean" }, "vatCategoryWarning": { "type": "string" }, "employer": { "type": "boolean" }, "fiscalYearEndMonth": { "type": "integer" }, "taxTypes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "frequency": { "type": "string" }, "lastFiledPeriod": { "type": "string" }, "lastFiledAt": { "type": "string" }, "lastStatus": { "type": "string" }, "nextDueDate": { "type": "string", "format": "date" }, "nextDuePeriod": { "type": "string" } } } } } }, "example": { "isvConfigured": false, "entityName": "Karoo Fresh Holdings Ltd", "vatNumber": "4123456789", "vatRegistered": false, "vatCategory": "Office supplies", "vatCategoryLabel": "Karoo Fresh Holdings Ltd", "vatCategoryAssumed": false, "vatCategoryWarning": "text", "employer": false, "fiscalYearEndMonth": 2, "taxTypes": [ { "code": "CT-001", "title": "Karoo Fresh Holdings Ltd", "frequency": "monthly", "lastFiledPeriod": "2026-09", "lastFiledAt": "2026-09-01T09:15:00Z", "lastStatus": "sent", "nextDueDate": "2026-09-01", "nextDuePeriod": "2026-09" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/group-overview": { "get": { "tags": [ "SARS returns" ], "summary": "Every company the caller may open — live, in this tenant, and within their company assignments — each with its legal form and the same returns, next due dates, latest filings and overdue returns as its own GET /api/sars/overview. Tenant-wide: send no X-Company-Id. The API sandbox is left out. Needs sars:view.", "operationId": "getApiSarsGroupOverview", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "legalForm": { "type": "string" }, "legalFormLabel": { "type": "string" }, "overview": { "type": "object", "properties": { "isvConfigured": { "type": "boolean" }, "entityName": { "type": "string" }, "vatRegistered": { "type": "boolean" }, "vatCategory": { "type": "string" }, "fiscalYearEndMonth": { "type": "integer" }, "legalForm": { "type": "string" }, "taxTypes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "frequency": { "type": "string" }, "nextDueDate": { "type": "string", "format": "date" }, "nextDuePeriod": { "type": "string" } } } } } } } } } } }, "example": { "companies": [ { "companyId": "7f6c1a2e-0000-4000-8000-000000000010", "name": "Dlamini & Venter", "legalForm": "PARTNERSHIP", "legalFormLabel": "Partnership", "overview": { "isvConfigured": false, "entityName": "Dlamini & Venter", "vatRegistered": false, "vatCategory": "NONE", "fiscalYearEndMonth": 2, "legalForm": "PARTNERSHIP", "taxTypes": [ { "code": "IT14", "title": "ITR12 business income schedule", "frequency": "Annual", "nextDueDate": "2027-01-18", "nextDuePeriod": "Year ending Feb 2026" } ] } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents": { "get": { "tags": [ "SARS returns" ], "summary": "Which returns can be produced, and for which periods.", "operationId": "getApiSarsDocuments", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "entityName": { "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "taxType": { "type": "string" }, "title": { "type": "string" }, "frequency": { "type": "string" }, "submissionChannel": { "type": "string" }, "formats": { "type": "array", "items": { "type": "string" } }, "path": { "type": "string" }, "parameters": { "type": "array", "items": { "type": "string" } }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string" } } } }, "easyFileUnverifiedCodes": { "type": "array", "items": { "type": "string" } }, "manualSubmissionOnly": { "type": "boolean" } } }, "example": { "entityName": "Karoo Fresh Holdings Ltd", "documents": [ { "taxType": "VAT201", "title": "Karoo Fresh Holdings Ltd", "frequency": "monthly", "submissionChannel": "email", "formats": [ "CSV" ], "path": "text", "parameters": [ "text" ], "available": true, "unavailableReason": "Budget deferred to the next financial year." } ], "easyFileUnverifiedCodes": [ "CT-001" ], "manualSubmissionOnly": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/vat201": { "get": { "tags": [ "SARS returns" ], "summary": "The VAT201. Output-tax supplies come from one owner — OutputTaxSupplies in shared — because omitting credit notes, debit notes and deposits once declared a refund of R6 353.49 where R6 336.81 was payable.", "operationId": "getApiSarsDocumentsVat201", "description": "Requires the `vat-returns:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "corrected", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-07-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-31" }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsDocumentsIrp6Response" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsDocumentsIrp6ResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/emp201": { "get": { "tags": [ "SARS returns" ], "summary": "The EMP201 — PAYE, UIF, SDL and the ETI set off against them.", "operationId": "getApiSarsDocumentsEmp201", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2026" }, { "name": "month", "in": "query", "required": false, "description": "Month of the year, 1-12. Refused rather than defaulted.", "schema": { "type": "integer" }, "example": "8" }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsDocumentsIrp6Response" }, "example": { "taxType": "EMP201", "title": "Karoo Fresh Holdings Ltd", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "periodLabel": "2026-09", "entityName": "Karoo Fresh Holdings Ltd", "taxReferenceNumber": "INV-0001", "sections": [ { "title": "Karoo Fresh Holdings Ltd", "note": "Budget deferred to the next financial year.", "fields": [ { "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "kind": "invoice", "amount": 10005.0, "display": "text", "unmapped": false, "confidence": "text", "note": "Budget deferred to the next financial year." } ] } ], "issues": [], "blockingIssues": [ "The control account and the age analysis differ by R0.00." ], "warnings": [], "unmappedFields": [ "text" ], "unverifiedFieldCodes": [ "CT-001" ], "derivedPaymentReference": "INV-0001", "netAmount": 8700.0, "isRefund": false, "availableFormats": [ "CSV" ], "manualSubmissionOnly": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/emp501": { "get": { "tags": [ "SARS returns" ], "summary": "The EMP501 bi-annual reconciliation.", "operationId": "getApiSarsDocumentsEmp501", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "taxYear", "in": "query", "required": false, "description": "South African year of assessment, named by the year it ENDS in: 2027 is 1 March 2026 to 28 February 2027. A year Ledgr holds no tables for is refused outright rather than served from the nearest one.", "schema": { "type": "integer" }, "example": "2027" }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" }, { "name": "period", "in": "query", "required": false, "description": "Which of a return's periods this is. Refused rather than defaulted.", "schema": { "type": "integer" }, "example": "2" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsDocumentsIrp6Response" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsDocumentsIrp6ResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/irp5": { "get": { "tags": [ "SARS returns" ], "summary": "IRP5/IT3(a) certificates, reviewed per employee before generation — e@syFile rejects a whole import on one bad record.", "operationId": "getApiSarsDocumentsIrp5", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "taxYear", "in": "query", "required": false, "description": "South African year of assessment, named by the year it ENDS in: 2027 is 1 March 2026 to 28 February 2027. A year Ledgr holds no tables for is refused outright rather than served from the nearest one.", "schema": { "type": "integer" }, "example": "2027" }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "easyfile" }, { "name": "layout", "in": "query", "required": false, "schema": { "type": "string" }, "example": "BRS" }, { "name": "period", "in": "query", "required": false, "description": "Which of a return's periods this is. Refused rather than defaulted.", "schema": { "type": "integer" }, "example": "2" } ], "responses": { "200": { "description": "A plain-text download.", "content": { "text/plain": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/itr14": { "get": { "tags": [ "SARS returns" ], "summary": "The annual income tax return the legal form files (ITR14, ITR12T, ITR12EI, or the owner's or partners' ITR12 business income schedule). For a partnership it carries the partnership's schedule and one per partner; `partner=` answers that one partner's share alone, for their own ITR12 — each line is the partnership's × their share, the largest share carrying the rounding so the partners add up to the cent. The account-type alias is folded once, in Itr14TrialBalanceLine's constructor, because an imported chart labelling its accounts `revenue` rather than `income` once reported nil turnover.", "operationId": "getApiSarsDocumentsItr14", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" }, { "name": "partner", "in": "query", "required": false, "schema": { "type": "string" }, "example": "7f6c1a2e-0000-4000-8000-000000000011" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsDocumentsIrp6Response" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsDocumentsIrp6ResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/itr14/trial-balance": { "get": { "tags": [ "SARS returns" ], "summary": "The trial-balance CSV that ships as the ITR14's supporting schedule.", "operationId": "getApiSarsDocumentsItr14TrialBalance", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "csv" } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/irp6": { "get": { "tags": [ "SARS returns" ], "summary": "The IRP6 provisional tax return.", "operationId": "getApiSarsDocumentsIrp6", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" }, { "name": "period", "in": "query", "required": false, "description": "Which of a return's periods this is. Refused rather than defaulted.", "schema": { "type": "integer" }, "example": "1" }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" }, { "name": "basis", "in": "query", "required": false, "schema": { "type": "string" }, "example": "annualised" }, { "name": "estimate", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "150000" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsDocumentsIrp6Response" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsDocumentsIrp6ResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/dividends": { "get": { "tags": [ "SARS returns" ], "summary": "Dividend declarations behind the DTR01/DTR02.", "operationId": "getApiSarsDocumentsDividends", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "declarations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "declarationDate": { "type": "string", "format": "date" }, "paymentDate": { "type": "string", "format": "date" }, "dividendDeclared": { "type": "number" }, "exemptAmount": { "type": "number" }, "taxableAmount": { "type": "number" }, "dividendsTax": { "type": "number" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "beneficialOwners": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiSarsDocumentsDividendsResponseBeneficialOwnersItem" } }, "dueDate": { "type": "string", "format": "date" }, "statutoryRatePercent": { "type": "number" }, "blockingIssues": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" } } } } } }, "example": { "declarations": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "declarationDate": "2026-09-01", "paymentDate": "2026-09-01", "dividendDeclared": 1.0, "exemptAmount": 10005.0, "taxableAmount": 1305.0, "dividendsTax": 1305.0, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "beneficialOwners": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "kind": "standard", "taxReferenceNumber": "INV-0001", "identityOrRegistrationNumber": "2021/123456/07", "countryOfResidence": "text", "dividendAmount": 10005.0, "exemptAmount": 10005.0, "exemptionGround": "text", "exemptionReason": "Budget deferred to the next financial year.", "declarationReceivedDate": "2026-09-01", "treatyRatePercent": 15.0, "taxableAmount": 1305.0, "ratePercent": 15.0, "taxWithheld": 1305.0 } ], "dueDate": "2026-09-01", "statutoryRatePercent": 15.0, "blockingIssues": [ "The control account and the age analysis differ by R0.00." ], "createdAt": "2026-09-01T09:15:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "SARS returns" ], "summary": "Record a dividend declaration. It posts to the ledger: DR 3600 Dividends Declared / CR 2190 Shareholders for Dividends, then the dividends tax withheld moves to 2171 on the payment date. Refused without the date of the board's (a close corporation's members') resolution acknowledging the solvency and liquidity test (Companies Act s46; CC Act s51), or when payment is more than 120 business days after it; the books' side of the test is returned in solvencyTest.", "operationId": "postApiSarsDocumentsDividends", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "declarationDate": { "type": "string", "format": "date" }, "paymentDate": { "type": "string", "format": "date" }, "dividendDeclared": { "type": "number" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "beneficialOwners": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string" }, "taxReferenceNumber": { "type": "string" }, "identityOrRegistrationNumber": { "type": "string" }, "countryOfResidence": { "type": "string" }, "dividendAmount": { "type": "number" }, "exemptAmount": { "type": "number" }, "exemptionGround": { "type": "string" }, "exemptionReason": { "type": "string" }, "declarationReceivedDate": { "type": "string", "format": "date" }, "treatyRatePercent": { "type": "number" } } } }, "boardResolutionDate": { "type": "string", "format": "date" }, "solvencyAndLiquidityAcknowledged": { "type": "boolean" }, "clientId": { "type": "string" } } }, "example": { "declarationDate": "2026-08-15", "paymentDate": "2026-08-31", "dividendDeclared": 250000.0, "reference": "DIV-2026-01", "notes": "Budget deferred to the next financial year.", "beneficialOwners": [ { "name": "Karoo Fresh Holdings Ltd", "kind": "natural_person", "taxReferenceNumber": "INV-0001", "identityOrRegistrationNumber": "2021/123456/07", "countryOfResidence": "ZA", "dividendAmount": 10005.0, "exemptAmount": 10005.0, "exemptionGround": "resident_company", "exemptionReason": "Budget deferred to the next financial year.", "declarationReceivedDate": "2026-09-01", "treatyRatePercent": 15.0 } ], "boardResolutionDate": "2026-08-15", "solvencyAndLiquidityAcknowledged": true, "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "declarationDate": { "type": "string", "format": "date" }, "paymentDate": { "type": "string", "format": "date" }, "dividendDeclared": { "type": "number" }, "exemptAmount": { "type": "number" }, "taxableAmount": { "type": "number" }, "dividendsTax": { "type": "number" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "beneficialOwners": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiSarsDocumentsDividendsResponseBeneficialOwnersItem" } }, "dueDate": { "type": "string", "format": "date" }, "statutoryRatePercent": { "type": "number" }, "blockingIssues": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "solvencyTest": { "type": "object", "properties": { "boardResolutionDate": { "type": "string", "format": "date" }, "assets": { "type": "number" }, "liabilitiesAfter": { "type": "number" }, "currentAssets": { "type": "number" }, "currentLiabilitiesAfter": { "type": "number" }, "solventOnBooks": { "type": "boolean" }, "liquidOnBooks": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object" } } } } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "declarationDate": "2026-09-01", "paymentDate": "2026-09-01", "dividendDeclared": 1.0, "exemptAmount": 10005.0, "taxableAmount": 1305.0, "dividendsTax": 1305.0, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "beneficialOwners": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "kind": "standard", "taxReferenceNumber": "INV-0001", "identityOrRegistrationNumber": "2021/123456/07", "countryOfResidence": "text", "dividendAmount": 10005.0, "exemptAmount": 10005.0, "exemptionGround": "text", "exemptionReason": "Budget deferred to the next financial year.", "declarationReceivedDate": "2026-09-01", "treatyRatePercent": 15.0, "taxableAmount": 1305.0, "ratePercent": 15.0, "taxWithheld": 1305.0 } ], "dueDate": "2026-09-01", "statutoryRatePercent": 15.0, "blockingIssues": [ "The control account and the age analysis differ by R0.00." ], "createdAt": "2026-09-01T09:15:00Z", "solvencyTest": { "boardResolutionDate": "2026-08-15", "assets": 1250000.0, "liabilitiesAfter": 640000.0, "currentAssets": 480000.0, "currentLiabilitiesAfter": 390000.0, "solventOnBooks": true, "liquidOnBooks": true, "warnings": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/dividends/{id}": { "delete": { "tags": [ "SARS returns" ], "summary": "Remove a declaration, reversing its ledger journals.", "operationId": "deleteApiSarsDocumentsDividendsById", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/donation-receipts": { "get": { "tags": [ "SARS returns" ], "summary": "Section 18A donation receipts this company issued, newest first, one page at a time (?limit=50, at most 200; the next page is ?before=, so a receipt issued meanwhile never shifts it; ?page= still answers), and whether it may issue one.", "operationId": "getApiSarsDonationReceipts", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "applies": { "type": "boolean" }, "refusal": { "type": "null" }, "receipts": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiSarsDonationReceiptsResponse" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "applies": true, "refusal": null, "receipts": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "18A-00001", "donationDate": "2026-09-01", "amount": 5000.0, "nature": null, "contactId": "9b2e4d61-7a3c-4f85-b0d2-6e1f8a9c3b47", "donorName": "Thandi Mokoena", "donorTradingName": null, "donorAddress": "12 Long Street, Cape Town, 8001", "donorPhone": "0214441234", "donorEmail": "thandi@example.example", "donorNature": "INDIVIDUAL", "donorIdType": "SA_ID", "donorIdNumber": "8001015009087", "donorIdCountry": "ZA", "donorTaxNumber": "0123456789", "issuedAt": "2026-09-01T09:30:00+02:00", "lastSentAt": null, "lastSendDelivered": null } ], "total": 1, "page": 1, "limit": 50, "totalPages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "SARS returns" ], "summary": "Issue a numbered section 18A receipt for a donation; refused unless the company is an approved PBO with section 18A approval. A clientId (a UUID the client mints once per receipt) makes a re-send answer the receipt already issued (200, the same number) instead of issuing a second.", "operationId": "postApiSarsDonationReceipts", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "donationDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "nature": { "type": "null" }, "donorNature": { "type": "string" }, "donorIdType": { "type": "string" }, "donorIdNumber": { "type": "string" }, "donorIdCountry": { "type": "string" }, "donorTaxNumber": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "contactId": "9b2e4d61-7a3c-4f85-b0d2-6e1f8a9c3b47", "donationDate": "2026-09-01", "amount": 5000.0, "nature": null, "donorNature": "INDIVIDUAL", "donorIdType": "SA_ID", "donorIdNumber": "8001015009087", "donorIdCountry": "ZA", "donorTaxNumber": "0123456789", "clientId": "c4d8e2f1-6a3b-4e97-8d15-0b2f9a7c5e64" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsDonationReceiptsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "18A-00001", "donationDate": "2026-09-01", "amount": 5000.0, "nature": null, "contactId": "9b2e4d61-7a3c-4f85-b0d2-6e1f8a9c3b47", "donorName": "Thandi Mokoena", "donorTradingName": null, "donorAddress": "12 Long Street, Cape Town, 8001", "donorPhone": "0214441234", "donorEmail": "thandi@example.example", "donorNature": "INDIVIDUAL", "donorIdType": "SA_ID", "donorIdNumber": "8001015009087", "donorIdCountry": "ZA", "donorTaxNumber": "0123456789", "issuedAt": "2026-09-01T09:30:00+02:00", "lastSentAt": null, "lastSendDelivered": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/donation-receipts/{id}/pdf": { "get": { "tags": [ "SARS returns" ], "summary": "The receipt as the donor is sent it.", "operationId": "getApiSarsDonationReceiptsByIdPdf", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/donation-receipts/{id}/send": { "post": { "tags": [ "SARS returns" ], "summary": "Email the receipt to the donor; the attempt is recorded on their communication history.", "operationId": "postApiSarsDonationReceiptsByIdSend", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "error": { "type": "null" }, "receipt": { "type": "object", "properties": { "id": { "type": "string" }, "receiptNumber": { "type": "string" }, "donationDate": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "nature": { "type": "null" }, "contactId": { "type": "string" }, "donorName": { "type": "string" }, "donorTradingName": { "type": "null" }, "donorAddress": { "type": "string" }, "donorPhone": { "type": "string" }, "donorEmail": { "type": "string" }, "donorNature": { "type": "string" }, "donorIdType": { "type": "string" }, "donorIdNumber": { "type": "string" }, "donorIdCountry": { "type": "string" }, "donorTaxNumber": { "type": "string" }, "issuedAt": { "type": "string" }, "lastSentAt": { "type": "string" }, "lastSendDelivered": { "type": "boolean" } } } } }, "example": { "delivered": true, "error": null, "receipt": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receiptNumber": "18A-00001", "donationDate": "2026-09-01", "amount": 5000.0, "nature": null, "contactId": "9b2e4d61-7a3c-4f85-b0d2-6e1f8a9c3b47", "donorName": "Thandi Mokoena", "donorTradingName": null, "donorAddress": "12 Long Street, Cape Town, 8001", "donorPhone": "0214441234", "donorEmail": "thandi@example.example", "donorNature": "INDIVIDUAL", "donorIdType": "SA_ID", "donorIdNumber": "8001015009087", "donorIdCountry": "ZA", "donorTaxNumber": "0123456789", "issuedAt": "2026-09-01T09:30:00+02:00", "lastSentAt": "2026-09-01T09:35:00+02:00", "lastSendDelivered": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/dtr01/{declarationId}": { "get": { "tags": [ "SARS returns" ], "summary": "The DTR01 for one declaration.", "operationId": "getApiSarsDocumentsDtr01ByDeclarationId", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "declarationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" } ], "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/tt03": { "get": { "tags": [ "SARS returns" ], "summary": "The TT03 turnover-tax return working document for the year of assessment ending in February of `year` (default: the year just ended): the amounts received in the year, the tax on the table, the interim payments made (money paid to SARS, not interims noted as filed) and the balance. Prepare-and-download only. A year the company is not registered for blocks (TT_NOT_REGISTERED). Needs sars:view; files need sars:export.", "operationId": "getApiSarsDocumentsTt03", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsDocumentsIt3dResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsDocumentsIt3dResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/it3d": { "get": { "tags": [ "SARS returns" ], "summary": "The IT3(d) working document of the section 18A receipts an approved public benefit organisation issued, for `period` first (1 March to 31 August, due 31 October) or year (the full year of assessment ending in February of `year`, due 31 May): the receipts issued and their rand value, the donations received on Donations Received (4160) in the same months, the difference, and each side's unmatched entries listed (receipts with no donation; donations with no receipt). Refused with 409 unless the company is an approved PBO with a section 18A approval. Prepare-and-download only. Needs sars:view; files need sars:export.", "operationId": "getApiSarsDocumentsIt3d", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" }, { "name": "period", "in": "query", "required": false, "description": "Which of a return's periods this is. Refused rather than defaulted.", "schema": { "type": "string" }, "example": "first" }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsDocumentsIt3dResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsDocumentsIt3dResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/it3t": { "get": { "tags": [ "SARS returns" ], "summary": "The IT3(t) working document of what a trust vested in each beneficiary in the year of assessment ending in February of `year` (default: the last completed year): the year's debits less credits to 3700 Distributions Vested in Beneficiaries, by the beneficiary named as the line's contact, each divided between local interest (source code 4201) and other income (4214) in proportion to the trust's income for the year (the conduit principle, s25B), the total vested (which the ITR12T deducts under section 25B), and a warning for any vesting that names no beneficiary. Refused with 409 unless the company is a trust. Prepare-and-download only: Ledgr does not write SARS's IT3(t) file. Needs sars:view; files need sars:export.", "operationId": "getApiSarsDocumentsIt3t", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsDocumentsIt3dResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsDocumentsIt3dResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/documents/it3d/file": { "post": { "tags": [ "SARS returns" ], "summary": "The IT3(d) as a file in SARS's External BRS IT3 Data Submission layout (v4.0.0D-10, section 6.5): pipe-delimited Latin-1 records, one donor record per donor and one donation record per receipt, with a trailer that counts and hashes them. `sourceIdentifier` is the 144-character token SARS issues the submitter; it is written into the file and never stored. `testData` marks the file for SARS's test environment. A return with a blocking issue answers 422; a company that is not an approved PBO with a section 18A approval answers 409. Ledgr does not transmit it. Needs sars:export.", "operationId": "postApiSarsDocumentsIt3dFile", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer" }, "period": { "type": "string" }, "sourceIdentifier": { "type": "string" }, "testData": { "type": "boolean" } } }, "example": { "year": 2027, "period": "first", "sourceIdentifier": "", "testData": true } } } }, "responses": { "201": { "description": "A plain-text download.", "content": { "text/plain": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat201": { "get": { "tags": [ "SARS returns" ], "summary": "The computed VAT201 boxes, as the screen renders them.", "operationId": "getApiSarsVat201", "description": "Requires the `vat-returns:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-07-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-31" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "periodLabel": { "type": "string" }, "standardRatedSales": { "type": "number" }, "zeroRatedSales": { "type": "number" }, "exemptSupplies": { "type": "number" }, "outputVat": { "type": "number" }, "inputVat": { "type": "number" }, "unclaimableInputTax": { "type": "number" }, "apportionmentPercent": { "type": "number" }, "netVat": { "type": "number" }, "entityName": { "type": "string" }, "vatNumber": { "type": "string" }, "vatRegistered": { "type": "boolean" }, "vatCategory": { "type": "string" }, "vatCategoryLabel": { "type": "string" }, "vatCategoryAssumed": { "type": "boolean" }, "vatCategoryWarning": { "type": "string" }, "isvConfigured": { "type": "boolean" } } }, "example": { "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "periodLabel": "2026-09", "standardRatedSales": 1.0, "zeroRatedSales": 1.0, "exemptSupplies": 1.0, "outputVat": 1305.0, "inputVat": 1305.0, "unclaimableInputTax": 1305.0, "apportionmentPercent": 15.0, "netVat": 1305.0, "entityName": "Karoo Fresh Holdings Ltd", "vatNumber": "4123456789", "vatRegistered": false, "vatCategory": "Office supplies", "vatCategoryLabel": "Karoo Fresh Holdings Ltd", "vatCategoryAssumed": false, "vatCategoryWarning": "text", "isvConfigured": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/section-24c-claims": { "get": { "tags": [ "SARS returns" ], "summary": "The section 24C claims recorded for a year end and the cap the books put on them: one claim per identified contract, the allowance the lesser of the income received in advance and the expenditure still to be incurred, limited to the income received in advance the books hold. The ITR14 deducts it and deferred tax reads the same.", "operationId": "getApiSarsSection24cClaims", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "yearEnd", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsSection24cClaimsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsSection24cClaimsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "SARS returns" ], "summary": "Record the section 24C allowance claimed on one identified contract at a year end. Refuses (400) a claim with no contract reference or date, amounts at or below nil, a contract concluded after the year end, or a date that is not the end of a year of assessment (the company's year end; February for a trust or a sole proprietor).", "operationId": "postApiSarsSection24cClaims", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "yearEnd": { "type": "string", "format": "date" }, "contractRef": { "type": "string" }, "contractDate": { "type": "string", "format": "date" }, "contactId": { "type": "string" }, "incomeReceivedInAdvance": { "type": "number" }, "futureExpenditure": { "type": "number" }, "note": { "type": "string" } } }, "example": { "yearEnd": "2026-02-28", "contractRef": "SLA-2025-14", "contractDate": "2025-11-03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a05", "incomeReceivedInAdvance": 18000.0, "futureExpenditure": 10000.0, "note": "Annual support contract" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsSection24cClaimsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsSection24cClaimsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/section-24c-claims/{id}": { "delete": { "tags": [ "SARS returns" ], "summary": "Take a section 24C claim back; the ITR14 and deferred tax stop reading it. Answers the year end's claims.", "operationId": "deleteApiSarsSection24cClaimsById", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsSection24cClaimsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsSection24cClaimsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/prepaid-expenses": { "get": { "tags": [ "SARS returns" ], "summary": "The prepaid expenses register at a date beside account 1330: each payment with whether section 23H defers it (supplied within six months after the year end, or R100 000 or less, is deducted when paid), what is unexpired, the expense account it is released to and what the month ends have released to it by the date, and the part of 1330 the register does not explain.", "operationId": "getApiSarsPrepaidExpenses", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsPrepaidExpensesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsPrepaidExpensesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "SARS returns" ], "summary": "Classify a payment held in 1330 as a prepaid expense: what it was, the day paid, the amount, the first and last day of the service and the expense account it is released to (optional: with one, each month end moves the month's share from 1330 to it, IFRS for SMEs 2.36). Refuses (400) a missing description or date, an amount at or below nil, a service that ended before the payment, and an expense account that is not an expense or cost-of-sales account in the company's chart.", "operationId": "postApiSarsPrepaidExpenses", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" }, "contactId": { "type": "string" }, "paidOn": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "serviceStart": { "type": "string", "format": "date" }, "serviceEnd": { "type": "string", "format": "date" }, "expenseAccountCode": { "type": "string" } } }, "example": { "description": "Software licence, 12 months", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a06", "paidOn": "2025-12-01", "amount": 60000.0, "serviceStart": "2025-12-01", "serviceEnd": "2026-11-30", "expenseAccountCode": "6230" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsPrepaidExpensesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsPrepaidExpensesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/prepaid-expenses/{id}": { "delete": { "tags": [ "SARS returns" ], "summary": "Take a prepaid expense out of the register; the ITR14 and deferred tax stop reading it. Answers the register today.", "operationId": "deleteApiSarsPrepaidExpensesById", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsPrepaidExpensesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsPrepaidExpensesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat201/pre-filing-check": { "get": { "tags": [ "SARS returns" ], "summary": "What to look at before a VAT201 is noted as filed: the VAT control tie, bank lines in the period not booked, purchases whose input tax was withheld for want of the supplier's VAT number, documents captured after the return was prepared, and apportionment. Advice only; each warning names its remedy.", "operationId": "getApiSarsVat201PreFilingCheck", "description": "Requires the `vat-returns:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-07-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-31" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "items": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "remedy": { "type": "string" }, "amount": { "type": "number" }, "count": { "type": "integer" } } } } } }, "example": { "periodStart": "2026-07-01", "periodEnd": "2026-08-31", "items": [ { "code": "input_withheld", "severity": "warn", "title": "1 purchase left out R1 500.00 of input tax for want of the supplier's VAT number", "detail": "A purchase over R5 000 is claimed only with the supplier's VAT number on a tax invoice (VAT Act s16(2) and s20); these were posted to cost instead, so the return does not claim them.", "remedy": "Add the supplier's VAT number to the contact (the purchase is claimed from then on), or leave it as cost if the supplier is not a vendor.", "amount": 1500.0, "count": 1 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat201/submit": { "post": { "tags": [ "SARS returns" ], "summary": "Note the VAT201 for a period as filed. The reference recorded is LEDGR'S OWN — nothing is transmitted to SARS. Optionally keep what eFiling issued: sarsReference, filedOn, and the payment (paidOn with paidAmount); a date before the period ended or in the future is refused (400). Refuses (409) a window that is not one ended VAT period of the company's category, or that overlaps a return already filed.", "operationId": "postApiSarsVat201Submit", "description": "Requires the `vat-returns:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "sarsReference": { "type": "string" }, "filedOn": { "type": "string", "format": "date" }, "paidOn": { "type": "string", "format": "date" }, "paidAmount": { "type": "number" } } }, "example": { "periodStart": "2026-07-01", "periodEnd": "2026-08-31", "sarsReference": "EFL-2026-0007", "filedOn": "2026-09-03", "paidOn": "2026-09-03", "paidAmount": 18450.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsIrp6SubmitResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsIrp6SubmitResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/sbc": { "get": { "tags": [ "SARS returns" ], "summary": "The company's answers to the five s12E small business corporation tests for a year of assessment, and whether it qualifies (null until every test is answered, false on any no). A qualifying company's ITR14 and IRP6 are taxed on the SBC table for the year; an unanswered year is asked about on both returns. grossIncomeOnLedger is the year's income on the books, beside the R20 million test.", "operationId": "getApiSarsSbc", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "yearEnd", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsSbcResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsSbcResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "SARS returns" ], "summary": "Answer the five s12E tests for a year of assessment. A yes to the R20 million gross income test is refused when the books show more. Needs sars:edit.", "operationId": "putApiSarsSbc", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "yearEnd": { "type": "string", "format": "date" }, "shareholdersAllNaturalPersons": { "type": "boolean" }, "grossIncomeWithinLimit": { "type": "boolean" }, "noSharesInOtherCompanies": { "type": "boolean" }, "investmentAndServiceIncomeWithinLimit": { "type": "boolean" }, "notPersonalServiceProvider": { "type": "boolean" } } }, "example": { "yearEnd": "2027-02-28", "shareholdersAllNaturalPersons": true, "grossIncomeWithinLimit": true, "noSharesInOtherCompanies": true, "investmentAndServiceIncomeWithinLimit": true, "notPersonalServiceProvider": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsSbcResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsSbcResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat-basis": { "get": { "tags": [ "SARS returns" ], "summary": "The company's VAT accounting basis today (invoice or payments), every dated change, and why it could not move onto the payments basis today (null when it qualifies). Needs sars:view.", "operationId": "getApiSarsVatBasis", "description": "Requires the `vat-returns:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsVatBasisResponse" }, "example": { "current": "payments", "changes": [ { "basis": "payments", "effectiveFrom": "2026-09-01" } ], "paymentsRefusal": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "SARS returns" ], "summary": "Record the VAT accounting basis from the first day of a tax period. The payments basis is refused for a company that is not a natural person or whose taxable supplies over the last twelve months exceed R2.5 million. Needs sars:edit.", "operationId": "putApiSarsVatBasis", "description": "Requires the `vat-returns:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiSarsVatBasisRequest" }, "example": { "basis": "payments", "effectiveFrom": "2026-09-01" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsVatBasisResponse" }, "example": { "current": "payments", "changes": [ { "basis": "payments", "effectiveFrom": "2026-09-01" } ], "paymentsRefusal": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/turnover-tax": { "get": { "tags": [ "SARS returns" ], "summary": "A micro business's turnover-tax estimate for a year of assessment: turnover so far and projected, the tax on the published table, both interim payments with their dates, and the TT03 window. A turnover above the limit is warned by name. Needs sars:view.", "operationId": "getApiSarsTurnoverTax", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsTurnoverTaxResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsTurnoverTaxResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/turnover-tax/registration": { "put": { "tags": [ "SARS returns" ], "summary": "Record that the company is (or is no longer) registered for turnover tax from 1 March of the year of assessment ending in February of `year`. Needs sars:edit.", "operationId": "putApiSarsTurnoverTaxRegistration", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer" }, "registered": { "type": "boolean" } } }, "example": { "year": 2027, "registered": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsTurnoverTaxResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsTurnoverTaxResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/turnover-tax/submit": { "post": { "tags": [ "SARS returns" ], "summary": "Record a turnover-tax interim payment (`interim1`, `interim2`) or the TT03 (`tt03`) as filed on the filing register for the year of assessment ending in February of `year`; its row then leaves the deadline card. Prepare-and-download only: nothing is sent to SARS. Refused 409 for a year the company is not registered for. Needs sars:create.", "operationId": "postApiSarsTurnoverTaxSubmit", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer" }, "kind": { "type": "string" } } }, "example": { "year": 2027, "kind": "interim2" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsIrp6SubmitResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a04", "submissionType": "TT_INTERIM", "periodStart": "2026-09-01", "periodEnd": "2027-02-28", "totalPaye": 0.0, "totalUif": 0.0, "totalSdl": 0.0, "totalEti": 0.0, "totalPayable": 0.0, "totalDue": 4250.0, "status": "SUBMITTED", "referenceNumber": "TT_INTERIM-202702-A1B2C3", "submittedAt": "2027-02-20T09:15:00Z", "createdAt": "2027-02-20T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/partners": { "get": { "tags": [ "SARS returns" ], "summary": "A partnership's partners and their shares for the ITR14 year ending in `year` (default: the last completed year) — the set in force at the year end, the one the partners' ITR12 schedules split by. Needs sars:view, not multicompany:view.", "operationId": "getApiSarsPartners", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string" }, "partnership": { "type": "boolean" }, "partners": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "taxNumber": { "type": "string" }, "sharePercent": { "type": "number" } } } }, "totalPercent": { "type": "number" } } }, "example": { "companyId": "7f6c1a2e-0000-4000-8000-000000000010", "partnership": true, "partners": [ { "id": "7f6c1a2e-0000-4000-8000-000000000011", "name": "Thandi Dlamini", "taxNumber": "0123456789", "sharePercent": 60.0 }, { "id": "7f6c1a2e-0000-4000-8000-000000000012", "name": "Pieter Venter", "sharePercent": 40.0 } ], "totalPercent": 100.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat-adjustments": { "get": { "tags": [ "SARS returns" ], "summary": "The VAT adjustments recorded in a period, newest first: bad debts written off (VAT201 field 17) and recovered (field 12), and changes in use (fields 9/11 and 16), each with its reason and document. Defaults to the most recent closed VAT period. At most 500. Needs sars:view.", "operationId": "getApiSarsVatAdjustments", "description": "Requires the `vat-returns:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "adjustments": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiSarsVatAdjustmentsResponse" } }, "limit": { "type": "integer" } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "adjustments": [ { "id": "7f6c1a2e-0000-4000-8000-000000000001", "kind": "bad_debt_written_off", "kindLabel": "Bad debt written off", "field": "17", "date": "2026-09-30", "invoiceId": "7f6c1a2e-0000-4000-8000-000000000002", "invoiceNumber": "INV-0042", "consideration": 11500.0, "vatAmount": 1500.0, "reason": "Customer liquidated; claim lodged with the liquidator", "documentRef": "Liquidator's letter 2026/118", "billId": null, "assetId": null } ], "limit": 500 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "SARS returns" ], "summary": "Record a VAT adjustment with its reason. `bad_debt_written_off` writes `amount` (including VAT, at most the invoice's amount due) off and claims back the invoice's own VAT share (DR 6300, DR 1340, CR 1320); `bad_debt_recovered` reinstates up to what was written off (DR 1320, CR 6300, CR 2130) so the payment is then recorded on the invoice as usual; `change_in_use_output` / `change_in_use_input` take the open-market value including VAT (CR 2130 or DR 1340 against 6345). A bad debt written off by a company that is not a VAT vendor on the date claims no VAT (DR 6300 / CR 1320 only, `vatAmount` 0) — the invoice's own door, POST /api/invoices/{id}/bad-debts, is the same writer on every plan. A change in use may name its fixed asset (`assetId`): a `change_in_use_input` naming one claims the tax fraction of the lesser of `amount` and the asset's cost less earlier s18(4) claims on it, and a cost already claimed in full is refused. A change in use is refused for a company that is not a VAT vendor; a vendor's debt on the payments basis and a blank reason are refused. Needs sars:edit.", "operationId": "postApiSarsVatAdjustments", "description": "Requires the `vat-returns:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "invoiceId": { "type": "string" }, "amount": { "type": "number" }, "date": { "type": "string", "format": "date" }, "reason": { "type": "string" }, "documentRef": { "type": "string" }, "billId": { "type": "string" }, "accountCode": { "type": "string" }, "assetId": { "type": "string" } } }, "example": { "kind": "bad_debt_written_off", "invoiceId": "7f6c1a2e-0000-4000-8000-000000000002", "amount": 11500.0, "date": "2026-09-30", "reason": "Customer liquidated; claim lodged with the liquidator", "documentRef": "Liquidator's letter 2026/118", "billId": "7f6c1a2e-0000-4000-8000-000000000002", "accountCode": "6340", "assetId": "7f6c1a2e-0000-4000-8000-000000000003" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsVatAdjustmentsResponse" }, "example": { "id": "7f6c1a2e-0000-4000-8000-000000000001", "kind": "bad_debt_written_off", "kindLabel": "Bad debt written off", "field": "17", "date": "2026-09-30", "invoiceId": "7f6c1a2e-0000-4000-8000-000000000002", "invoiceNumber": "INV-0042", "consideration": 11500.0, "vatAmount": 1500.0, "reason": "Customer liquidated; claim lodged with the liquidator", "documentRef": "Liquidator's letter 2026/118", "billId": null, "assetId": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat-review": { "get": { "tags": [ "SARS returns" ], "summary": "Past VAT in stored rows, each with its rand effect, tax period and route. Reads only.", "operationId": "getApiSarsVatReview", "description": "Requires the `vat-returns:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsVatReviewResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsVatReviewResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat-review/act": { "post": { "tags": [ "SARS returns" ], "summary": "The one press a finding offers: a posting or VAT adjustment on its own date, a release from a filed return's baseline, or a retype of an open period's export lines as a service, which posts nothing; a filed period's change reaches the correction schedule.", "operationId": "postApiSarsVatReviewAct", "description": "Requires the `vat-returns:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsVatReviewActRequest" }, "example": { "finding": "disposal:3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reason": "Checked with our accountant" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsVatReviewResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsVatReviewResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat-review/dismiss": { "post": { "tags": [ "SARS returns" ], "summary": "Record that a finding does not apply, with the reason. Nothing else moves.", "operationId": "postApiSarsVatReviewDismiss", "description": "Requires the `vat-returns:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsVatReviewActRequest" }, "example": { "finding": "disposal:3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reason": "Checked with our accountant" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsVatReviewResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsVatReviewResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat-review/undo": { "post": { "tags": [ "SARS returns" ], "summary": "Take a decision back, and the press with it.", "operationId": "postApiSarsVatReviewUndo", "description": "Requires the `vat-returns:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "finding": { "type": "string" } } }, "example": { "finding": "disposal:3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsVatReviewResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsVatReviewResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bills/{billId}/debit-notes": { "post": { "tags": [ "SARS returns" ], "summary": "Raise the supplier's debit note, a further charge that pays as a bill; field 18 when the bill was on a filed return.", "operationId": "postApiBillsByBillIdDebitNotes", "description": "Requires the `expenses:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "expenses:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "billId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "creditNoteNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "reason": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "vatRate": { "type": "number" } } } }, "clientId": { "type": "string" } } }, "example": { "creditNoteNumber": "DN-4471", "issueDate": "2026-09-30", "reason": "Under-charged", "lines": [ { "description": "Price correction", "quantity": 1.0, "unitPrice": 200.0, "vatRate": 15.0 } ], "clientId": "453b20f0-8fc1-50d0-9471-51761784522b" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "billNumber": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "DN-4471", "issueDate": "2026-09-30", "billNumber": "INV-1" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat-creditors": { "get": { "tags": [ "SARS returns" ], "summary": "Bills unpaid 12 months after the tax period of their deduction (s22(3)), and bills paid since their adjustment (s22(4)). Posts nothing.", "operationId": "getApiSarsVatCreditors", "description": "Requires the `vat-returns:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "type": "string" }, "unpaid": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsVatCreditorsResponseUnpaidItem" } }, "paidSince": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsVatCreditorsResponseUnpaidItem" } } } }, "example": { "asOf": "text", "unpaid": [ { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplier": "Karoo Fresh Holdings Ltd", "reference": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "twelveMonthsEnd": "2026-09-30", "adjustmentDate": "2026-09-01", "amount": 10005.0, "vatAmount": 1305.0, "groupCompany": false } ], "paidSince": [ { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplier": "Karoo Fresh Holdings Ltd", "reference": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "twelveMonthsEnd": "2026-09-30", "adjustmentDate": "2026-09-01", "amount": 10005.0, "vatAmount": 1305.0, "groupCompany": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat-deregistration": { "get": { "tags": [ "SARS returns" ], "summary": "Draft the final VAT201 of a company whose VAT registration ends on `date` (the last day of the final tax period; default today). Lists the stock (open batch layers) and fixed assets still held with the s10(5) value of the s8(2) deemed supply - the lesser of cost including VAT and open market value - and the bills whose claimed VAT is still unpaid (s22(3)). Once recorded, answers the recorded date and reason. Posts nothing. Needs sars:view.", "operationId": "getApiSarsVatDeregistration", "description": "Requires the `vat-returns:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "effectiveDate": { "type": "string", "format": "date" }, "recorded": { "type": "boolean" }, "reason": { "type": "null" }, "stock": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsVatDeregistrationResponseStockItem" } }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsVatDeregistrationResponseAssetsItem" } }, "creditors": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsVatDeregistrationResponseCreditorsItem" } }, "stockValue": { "type": "number" }, "stockVat": { "type": "number" }, "assetValue": { "type": "number" }, "assetVat": { "type": "number" }, "creditorVat": { "type": "number" } } }, "example": { "effectiveDate": "2026-09-30", "recorded": false, "reason": null, "stock": [ { "kind": "stock", "id": "7f6c1a2e-0000-4000-8000-000000000004", "name": "Cup", "costIncludingVat": 3450.0, "openMarketValue": null, "value": 3450.0, "vatAmount": 450.0 } ], "assets": [ { "kind": "asset", "id": "7f6c1a2e-0000-4000-8000-000000000003", "name": "Delivery bakkie", "costIncludingVat": 230000.0, "openMarketValue": 115000.0, "value": 115000.0, "vatAmount": 15000.0 } ], "creditors": [ { "billId": "7f6c1a2e-0000-4000-8000-000000000002", "reference": "INV-0001", "amount": 1150.0, "vatAmount": 150.0 } ], "stockValue": 3450.0, "stockVat": 450.0, "assetValue": 115000.0, "assetVat": 15000.0, "creditorVat": 150.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "SARS returns" ], "summary": "Cancel the company's VAT registration with `effectiveDate` as its last day as a vendor, for `reason`. Dated that day, it posts the s8(2) deemed supply of the stock (VAT201 fields 1 and 4) and capital assets (1A and 4A) still held at the s10(5) value - `openMarketValues` maps an item id to a lower open market value - (DR 6345 / CR 2130), and the s22(3) output tax on each bill still unpaid. After the date the company charges and claims no VAT, prints no VAT number and is asked for no VAT201. Refused for a company that is not a vendor on the date, one already deregistered, or a blank reason. Needs sars:edit.", "operationId": "postApiSarsVatDeregistration", "description": "Requires the `vat-returns:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "effectiveDate": { "type": "string", "format": "date" }, "reason": { "type": "string" }, "openMarketValues": { "type": "object", "properties": { "7f6c1a2e-0000-4000-8000-000000000003": { "type": "number" } } } } }, "example": { "effectiveDate": "2026-09-30", "reason": "Turnover below R1 million; SARS letter of 2026-09-15", "openMarketValues": { "7f6c1a2e-0000-4000-8000-000000000003": 115000.0 } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "effectiveDate": { "type": "string", "format": "date" }, "recorded": { "type": "boolean" }, "reason": { "type": "string" }, "stock": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsVatDeregistrationResponseStockItem" } }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsVatDeregistrationResponseAssetsItem" } }, "creditors": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsVatDeregistrationResponseCreditorsItem" } }, "stockValue": { "type": "number" }, "stockVat": { "type": "number" }, "assetValue": { "type": "number" }, "assetVat": { "type": "number" }, "creditorVat": { "type": "number" } } }, "example": { "effectiveDate": "2026-09-30", "recorded": true, "reason": "Turnover below R1 million; SARS letter of 2026-09-15", "stock": [ { "kind": "stock", "id": "7f6c1a2e-0000-4000-8000-000000000004", "name": "Cup", "costIncludingVat": 3450.0, "openMarketValue": null, "value": 3450.0, "vatAmount": 450.0 } ], "assets": [ { "kind": "asset", "id": "7f6c1a2e-0000-4000-8000-000000000003", "name": "Delivery bakkie", "costIncludingVat": 230000.0, "openMarketValue": 115000.0, "value": 115000.0, "vatAmount": 15000.0 } ], "creditors": [ { "billId": "7f6c1a2e-0000-4000-8000-000000000002", "reference": "INV-0001", "amount": 1150.0, "vatAmount": 150.0 } ], "stockValue": 3450.0, "stockVat": 450.0, "assetValue": 115000.0, "assetVat": 15000.0, "creditorVat": 150.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat-filed-periods": { "get": { "tags": [ "SARS returns" ], "summary": "The VAT periods noted as filed: dates only, for the prompt as a document is dated.", "operationId": "getApiSarsVatFiledPeriods", "description": "Requires the `vat-returns:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "periodLabel": { "type": "string" } } } }, "example": [ { "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "periodLabel": "2026-09" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/vat201/correction": { "post": { "tags": [ "SARS returns" ], "summary": "Note that the correction of a filed period was submitted on eFiling. Ledgr transmits nothing; the prepared figures become the filed return.", "operationId": "postApiSarsVat201Correction", "description": "Requires the `vat-returns:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "vat-returns:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "reference": { "type": "string" } } }, "example": { "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "reference": "RFC 1" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "noted": { "type": "boolean" } } }, "example": { "noted": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/periods/generate": { "post": { "tags": [ "SARS returns" ], "summary": "Make the twelve months of the financial year holding a date, skipping what exists.", "operationId": "postApiLedgerPeriodsGenerate", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLedgerBooksOpenResponse" }, "example": { "date": "2026-09-30" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "integer" } } }, "example": { "created": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/periods/lock-through": { "post": { "tags": [ "SARS returns" ], "summary": "Lock every period up to and including a period end. Needs approve rights.", "operationId": "postApiLedgerPeriodsLockThrough", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLedgerBooksOpenResponse" }, "example": { "date": "2026-09-30" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "locked": { "type": "integer" } } }, "example": { "locked": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ledger/year-end-checklist": { "get": { "tags": [ "SARS returns" ], "summary": "What is done and what is open for a year end. Posts nothing.", "operationId": "getApiLedgerYearEndChecklist", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "yearEnd", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "yearEnd": { "type": "string", "format": "date" }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" }, "detail": { "type": "string" } } } } } }, "example": { "yearEnd": "2026-09-30", "items": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd", "done": true, "detail": "Saved." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fixed-assets/{id}/impair": { "post": { "tags": [ "SARS returns" ], "summary": "Record an impairment loss, or its reversal, on one asset, with the reason.", "operationId": "postApiFixedAssetsByIdImpair", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "reason": { "type": "string" }, "reversal": { "type": "boolean" } } }, "example": { "date": "2026-09-30", "amount": 30000.0, "reason": "Fire damage", "reversal": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "assetNumber": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "assetClass": { "type": "string" }, "assetClassLabel": { "type": "string" }, "acquisitionDate": { "type": "string", "format": "date" }, "cost": { "type": "number" }, "residualValue": { "type": "number" }, "usefulLifeMonths": { "type": "integer" }, "usefulLifeReliable": { "type": "boolean" }, "method": { "type": "string" }, "ratePercent": { "type": "number" }, "accumulatedDepreciation": { "type": "number" }, "bookValue": { "type": "number" }, "depreciatedTo": { "type": "string", "format": "date" }, "status": { "type": "string" }, "disposalDate": { "type": "string", "format": "date" }, "disposalProceeds": { "type": "number" }, "disposalOutputVat": { "type": "number" }, "serialNumber": { "type": "string" }, "location": { "type": "string" }, "costCentreId": { "type": "string" }, "costCentreCode": { "type": "string" }, "supplierContactId": { "type": "string" }, "notes": { "type": "string" }, "monthsRemaining": { "type": "integer" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "assetNumber": "INV-0001", "name": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "assetClass": "text", "assetClassLabel": "Karoo Fresh Holdings Ltd", "acquisitionDate": "2026-09-01", "cost": 10005.0, "residualValue": 10005.0, "usefulLifeMonths": 1, "usefulLifeReliable": true, "method": "eft", "ratePercent": 15.0, "accumulatedDepreciation": 1.0, "bookValue": 10005.0, "depreciatedTo": "2026-09-30", "status": "sent", "disposalDate": "2026-09-01", "disposalProceeds": 1.0, "disposalOutputVat": 1305.0, "serialNumber": "INV-0001", "location": "text", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreCode": "CT-001", "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "monthsRemaining": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/loans": { "get": { "tags": [ "SARS returns" ], "summary": "The loan register at a date (today by default): each loan's terms, the capital still owed on its schedule, the interest accrued since the last instalment and the part due within twelve months, and the register's tie to each loan account and to the interest accrued.", "operationId": "getApiLoans", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asAt", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-10-31" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asAt": { "type": "string", "format": "date" }, "loans": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLoansResponse" } }, "outstanding": { "type": "number" }, "accruedInterest": { "type": "number" }, "currentPortion": { "type": "number" }, "nonCurrentPortion": { "type": "number" }, "ties": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "ledger": { "type": "number" }, "subledger": { "type": "number" }, "difference": { "type": "number" }, "ties": { "type": "boolean" }, "note": { "type": "string" } } } } } }, "example": { "asAt": "2026-10-31", "loans": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "ABSA term loan", "lenderName": "ABSA Bank", "accountCode": "2010", "principal": 240000.0, "annualRatePercent": 11.0, "advanceDate": "2026-04-01", "termMonths": 24, "firstInstalmentDate": "2026-05-01", "instalment": 11185.88, "maturityDate": "2028-04-01", "securityDescription": "a cession of book debts", "outstanding": 184833.96, "accruedInterest": 1694.31, "currentPortion": 119820.37, "nonCurrentPortion": 65013.59, "accruedPeriodEnds": [ "2026-10-31" ], "transactionCosts": 4800.0, "marketRatePercent": null, "lenderIsOwner": false, "effectiveRatePercent": 13.04, "initialCarryingAmount": 235200.0, "dayOneDifference": 0.0, "carryingAmount": 182271.57 } ], "outstanding": 184833.96, "accruedInterest": 1694.31, "currentPortion": 119820.37, "nonCurrentPortion": 65013.59, "ties": [ { "code": "LOAN-2010", "name": "Loans: Long-term Loans (2010)", "ledger": 184833.96, "subledger": 184833.96, "difference": 0.0, "ties": true, "note": "The principal of the loans booked to 2010 less the capital of every instalment due by 2026-10-31 (the loan register's schedule)." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "SARS returns" ], "summary": "Register a borrowing: the lender, the loan account it is booked to (2010 or 2020), the amount, the yearly rate, the advance date, the term in monthly instalments and the first instalment (the bank's stated instalment where it has one). The schedule is worked from these terms. Fees paid to arrange it and, for a loan below a market rate, that market rate carry it at amortised cost (IFRS for SMEs 11.13-11.20): a below-market loan's day-one difference is posted on the advance date, to equity when the lender is an owner, else to profit.", "operationId": "postApiLoans", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "lenderName": { "type": "string" }, "accountCode": { "type": "string" }, "principal": { "type": "number" }, "annualRatePercent": { "type": "number" }, "advanceDate": { "type": "string", "format": "date" }, "termMonths": { "type": "integer" }, "firstInstalmentDate": { "type": "string", "format": "date" }, "instalment": { "type": "number" }, "securityDescription": { "type": "string" }, "transactionCosts": { "type": "number" }, "marketRatePercent": { "type": "null" }, "lenderIsOwner": { "type": "boolean" } } }, "example": { "name": "ABSA term loan", "lenderName": "ABSA Bank", "accountCode": "2010", "principal": 240000.0, "annualRatePercent": 11.0, "advanceDate": "2026-04-01", "termMonths": 24, "firstInstalmentDate": "2026-05-01", "instalment": 11185.88, "securityDescription": "a cession of book debts", "transactionCosts": 4800.0, "marketRatePercent": null, "lenderIsOwner": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLoansResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "ABSA term loan", "lenderName": "ABSA Bank", "accountCode": "2010", "principal": 240000.0, "annualRatePercent": 11.0, "advanceDate": "2026-04-01", "termMonths": 24, "firstInstalmentDate": "2026-05-01", "instalment": 11185.88, "maturityDate": "2028-04-01", "securityDescription": "a cession of book debts", "outstanding": 184833.96, "accruedInterest": 1694.31, "currentPortion": 119820.37, "nonCurrentPortion": 65013.59, "accruedPeriodEnds": [ "2026-10-31" ], "transactionCosts": 4800.0, "marketRatePercent": null, "lenderIsOwner": false, "effectiveRatePercent": 13.04, "initialCarryingAmount": 235200.0, "dayOneDifference": 0.0, "carryingAmount": 182271.57 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/loans/{id}/schedule": { "get": { "tags": [ "SARS returns" ], "summary": "A loan's repayment schedule: each instalment's date, the interest and capital it pays, and what is owed after it.", "operationId": "getApiLoansByIdSchedule", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "loanId": { "type": "string" }, "name": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "opening": { "type": "number" }, "interest": { "type": "number" }, "capital": { "type": "number" }, "payment": { "type": "number" }, "closing": { "type": "number" }, "effectiveInterest": { "type": "number" }, "carryingAmount": { "type": "number" } } } } } }, "example": { "loanId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "ABSA term loan", "rows": [ { "number": 7, "date": "2026-11-01", "opening": 184833.96, "interest": 1694.31, "capital": 9491.57, "payment": 11185.88, "closing": 175342.39, "effectiveInterest": 1977.1, "carryingAmount": 172780.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/loans/{id}": { "delete": { "tags": [ "SARS returns" ], "summary": "Take a loan off the register. Refused (409) once interest has been accrued on it.", "operationId": "deleteApiLoansById", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/loans/accrue": { "post": { "tags": [ "SARS returns" ], "summary": "Accrue each loan's interest to a period end that has arrived: DR 6330 / CR 2121, taken back the next morning because the instalment pays that interest; for a loan with fees or a below-market discount, also the part of them charged as interest at the effective rate to that date (DR 6330 / CR the loan account, not reversed). Once per loan and period end; a repeat run accrues nothing.", "operationId": "postApiLoansAccrue", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "periodEnd", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-10-31" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodEnd": { "type": "string", "format": "date" }, "accrued": { "type": "array", "items": { "type": "object", "properties": { "loanId": { "type": "string" }, "name": { "type": "string" }, "interest": { "type": "number" }, "alreadyAccrued": { "type": "boolean" }, "discountUnwound": { "type": "number" } } } }, "totalInterest": { "type": "number" }, "totalUnwound": { "type": "number" } } }, "example": { "periodEnd": "2026-10-31", "accrued": [ { "loanId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "ABSA term loan", "interest": 1694.31, "alreadyAccrued": false, "discountUnwound": 2237.61 } ], "totalInterest": 1694.31, "totalUnwound": 2237.61 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fixed-assets/deferred-tax": { "get": { "tags": [ "SARS returns" ], "summary": "Deferred tax on the register at a year end: book value against tax value at the company rate. Posts nothing.", "operationId": "getApiFixedAssetsDeferredTax", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "yearEnd", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiFixedAssetsDeferredTaxResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiFixedAssetsDeferredTaxResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "SARS returns" ], "summary": "Take the deferred tax account to the calculated balance at a year end.", "operationId": "postApiFixedAssetsDeferredTax", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "yearEnd": { "type": "string", "format": "date" } } }, "example": { "yearEnd": "2027-02-28" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiFixedAssetsDeferredTaxResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiFixedAssetsDeferredTaxResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fixed-assets/deferred-tax/decline": { "post": { "tags": [ "SARS returns" ], "summary": "Record the policy of not recognising deferred tax, with the reason. A blank reason clears it.", "operationId": "postApiFixedAssetsDeferredTaxDecline", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdRejectRequest" }, "example": { "reason": "Micro entity policy" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "declined": { "type": "integer" } } }, "example": { "declined": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/contacts/contra": { "post": { "tags": [ "SARS returns" ], "summary": "Set one bill against the invoices of the same party, oldest as listed, up to what is still owed on the bill: invoices that cover it settle it, invoices owing less part-pay it. Every invoice must be owed by the bill's own supplier contact, and a bill with no supplier contact is refused (409). Rand documents only, and no VAT moves.", "operationId": "postApiContactsContra", "description": "Requires the `contacts:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "contacts:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "billId": { "type": "string" }, "invoiceIds": { "type": "array", "items": { "type": "string" } }, "date": { "type": "string", "format": "date" }, "reason": { "type": "string" } } }, "example": { "billId": "7f6c1a2e-0000-4000-8000-000000000001", "invoiceIds": [ "7f6c1a2e-0000-4000-8000-000000000002" ], "date": "2026-09-30", "reason": "Offset agreed" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "billId": { "type": "string" }, "amount": { "type": "number" }, "invoices": { "type": "array", "items": { "type": "string" } } } }, "example": { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 10005.0, "invoices": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/it14": { "get": { "tags": [ "SARS returns" ], "summary": "The company income tax estimate for a fiscal year.", "operationId": "getApiSarsIt14", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taxYearLabel": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "revenue": { "type": "number" }, "expenses": { "type": "number" }, "taxableIncome": { "type": "number" }, "taxAt27": { "type": "number" }, "provisionalPaid": { "type": "number" }, "balanceDue": { "type": "number" }, "estimate": { "type": "boolean" }, "returnCode": { "type": "string" }, "returnTitle": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "dueDateLabel": { "type": "string", "format": "date" }, "reconciliation": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsIt14ResponseReconciliationItem" } }, "netProfitBeforeTax": { "type": "number" }, "depreciationAddedBack": { "type": "number" }, "wearAndTear": { "type": "number" }, "assessedLossApplies": { "type": "boolean" }, "assessedLossBroughtForward": { "type": "number" }, "assessedLossSource": { "type": "string" }, "assessedLossLimit": { "type": "number" }, "assessedLossSetOff": { "type": "number" }, "assessedLossCarriedForward": { "type": "number" }, "donationsCharged": { "type": "number" }, "donationReceiptsHeld": { "type": "number" }, "donationsWithoutReceipt": { "type": "number" }, "issues": { "type": "array", "items": { "type": "object" } }, "wearAndTearIssues": { "type": "array", "items": { "type": "string" } } } }, "example": { "taxYearLabel": "2027", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "revenue": 1.0, "expenses": 1.0, "taxableIncome": 1305.0, "taxAt27": 1305.0, "provisionalPaid": 1.0, "balanceDue": 10005.0, "estimate": true, "returnCode": "CT-001", "returnTitle": "Karoo Fresh Holdings Ltd", "dueDate": "2026-09-01", "dueDateLabel": "2026-09-01", "reconciliation": [ { "label": "Karoo Fresh Holdings Ltd", "amount": 10005.0, "subtotal": false } ], "netProfitBeforeTax": 1305.0, "depreciationAddedBack": 1.0, "wearAndTear": 1.0, "assessedLossApplies": true, "assessedLossBroughtForward": 1.0, "assessedLossSource": "referral", "assessedLossLimit": 1.0, "assessedLossSetOff": 1.0, "assessedLossCarriedForward": 1.0, "donationsCharged": 1.0, "donationReceiptsHeld": 1.0, "donationsWithoutReceipt": 0.0, "issues": [], "wearAndTearIssues": [ "The control account and the age analysis differ by R0.00." ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/itr14/assessed-loss": { "put": { "tags": [ "SARS returns" ], "summary": "Record the balance of assessed loss brought forward into an ITR14 year, from your last SARS assessment. `yearEnd` is the last day of the financial year it is brought into; R0.00 records that the assessment shows none. It replaces the balance Ledgr would otherwise carry from its own computation of the previous year. The set-off is limited, for years ending on or after 31 March 2023, to the greater of R1 000 000 and 80% of taxable income before it. Answers with that year's estimate and its reconciliation. Needs sars:edit.", "operationId": "putApiSarsItr14AssessedLoss", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiSarsItr14AssessedLossRequest" }, "example": { "yearEnd": "2027-02-28", "amount": 30000.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taxYearLabel": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "revenue": { "type": "number" }, "expenses": { "type": "number" }, "taxableIncome": { "type": "number" }, "taxAt27": { "type": "number" }, "provisionalPaid": { "type": "number" }, "balanceDue": { "type": "number" }, "estimate": { "type": "boolean" }, "returnCode": { "type": "string" }, "returnTitle": { "type": "string" }, "reconciliation": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollCostToCompanyResponseComponentsItem" } }, "netProfitBeforeTax": { "type": "number" }, "depreciationAddedBack": { "type": "number" }, "wearAndTear": { "type": "number" }, "assessedLossApplies": { "type": "boolean" }, "assessedLossBroughtForward": { "type": "number" }, "assessedLossSource": { "type": "string" }, "assessedLossLimit": { "type": "number" }, "assessedLossSetOff": { "type": "number" }, "assessedLossCarriedForward": { "type": "number" }, "donationsCharged": { "type": "number" }, "donationReceiptsHeld": { "type": "null" }, "donationsWithoutReceipt": { "type": "number" }, "issues": { "type": "array", "items": { "type": "object" } } } }, "example": { "taxYearLabel": "2027", "periodStart": "2026-03-01", "periodEnd": "2027-02-28", "revenue": 500000.0, "expenses": 60000.0, "taxableIncome": 370000.0, "taxAt27": 99900.0, "provisionalPaid": 0.0, "balanceDue": 99900.0, "estimate": true, "returnCode": "ITR14", "returnTitle": "Company Income Tax Return (ITR14)", "reconciliation": [ { "label": "Net profit before tax per the income statement", "amount": 440000.0 }, { "label": "Add back: depreciation and amortisation", "amount": 10000.0 }, { "label": "Less: wear-and-tear, section 11(e)", "amount": -50000.0 }, { "label": "Taxable income before the assessed loss", "amount": 400000.0 }, { "label": "Less: assessed loss set off, section 20", "amount": -30000.0 }, { "label": "Taxable income per Ledgr", "amount": 370000.0 } ], "netProfitBeforeTax": 440000.0, "depreciationAddedBack": 10000.0, "wearAndTear": 50000.0, "assessedLossApplies": true, "assessedLossBroughtForward": 30000.0, "assessedLossSource": "typed", "assessedLossLimit": 1000000.0, "assessedLossSetOff": 30000.0, "assessedLossCarriedForward": 0.0, "donationsCharged": 0.0, "donationReceiptsHeld": null, "donationsWithoutReceipt": 0.0, "issues": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/itr14/donation-receipts": { "put": { "tags": [ "SARS returns" ], "summary": "Record the value of the section 18A receipts you hold for an ITR14 year's donations. `yearEnd` is the last day of the financial year the donations were made in; R0.00 records that there are none. A donation is deductible only against a section 18A receipt (Income Tax Act s18A(2)), so until this is entered no donation is deducted, and the part of the year's donations no receipt supports is added back and not carried forward. The receipted part is deducted to 10% of taxable income. Answers with that year's estimate and its reconciliation. Needs sars:edit.", "operationId": "putApiSarsItr14DonationReceipts", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiSarsItr14AssessedLossRequest" }, "example": { "yearEnd": "2027-02-28", "amount": 10000.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taxYearLabel": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "revenue": { "type": "number" }, "expenses": { "type": "number" }, "taxableIncome": { "type": "number" }, "taxAt27": { "type": "number" }, "provisionalPaid": { "type": "number" }, "balanceDue": { "type": "number" }, "taxNotStated": { "type": "null" }, "estimate": { "type": "boolean" }, "returnCode": { "type": "string" }, "returnTitle": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "dueDateLabel": { "type": "string" }, "reconciliation": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsIt14ResponseReconciliationItem" } }, "netProfitBeforeTax": { "type": "number" }, "depreciationAddedBack": { "type": "number" }, "wearAndTear": { "type": "number" }, "assessedLossApplies": { "type": "boolean" }, "assessedLossBroughtForward": { "type": "number" }, "assessedLossSource": { "type": "null" }, "assessedLossLimit": { "type": "null" }, "assessedLossSetOff": { "type": "number" }, "assessedLossCarriedForward": { "type": "number" }, "donationsCharged": { "type": "number" }, "donationReceiptsHeld": { "type": "number" }, "donationsWithoutReceipt": { "type": "number" }, "issues": { "type": "array", "items": { "type": "object" } }, "wearAndTearIssues": { "type": "array", "items": { "type": "object" } } } }, "example": { "taxYearLabel": "2027", "periodStart": "2026-03-01", "periodEnd": "2027-02-28", "revenue": 2000000.0, "expenses": 1660000.0, "taxableIncome": 360000.0, "taxAt27": 97200.0, "provisionalPaid": 0.0, "balanceDue": 97200.0, "taxNotStated": null, "estimate": true, "returnCode": "ITR14", "returnTitle": "Company Income Tax Return (ITR14)", "dueDate": "2028-02-28", "dueDateLabel": "Within 12 months of the year end", "reconciliation": [ { "label": "Net profit before tax per the income statement", "amount": 340000.0, "subtotal": false }, { "label": "Add back: donations without a section 18A receipt (section 18A(2))", "amount": 20000.0, "subtotal": false }, { "label": "Taxable income before the assessed loss", "amount": 360000.0, "subtotal": false }, { "label": "Less: assessed loss set off, section 20", "amount": 0.0, "subtotal": false }, { "label": "Taxable income per Ledgr", "amount": 360000.0, "subtotal": false } ], "netProfitBeforeTax": 340000.0, "depreciationAddedBack": 0.0, "wearAndTear": 0.0, "assessedLossApplies": true, "assessedLossBroughtForward": 0.0, "assessedLossSource": null, "assessedLossLimit": null, "assessedLossSetOff": 0.0, "assessedLossCarriedForward": 0.0, "donationsCharged": 30000.0, "donationReceiptsHeld": 10000.0, "donationsWithoutReceipt": 20000.0, "issues": [], "wearAndTearIssues": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/it14/current-tax": { "get": { "tags": [ "SARS returns" ], "summary": "The year's income tax as the books hold it (IFRS for SMEs 29.5): the ITR14's normal tax, what was paid to SARS, the income tax expense already in the books, the charge still to post (DR Income Tax Expense 6910 / CR Income Tax Payable 2170) and the payable at the year end. Posts nothing. A sole proprietor or a partnership pays no tax of the business's own, and a return that states no tax, so `notProposed` says why. Needs sars:view.", "operationId": "getApiSarsIt14CurrentTax", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsIt14CurrentTaxResponse" }, "example": { "yearEnd": "2027-02-28", "normalTax": 270000.0, "paidToSars": 200000.0, "charged": 0.0, "movement": 270000.0, "payable": -200000.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "SARS returns" ], "summary": "Post the year's income tax: DR Income Tax Expense (6910) / CR Income Tax Payable (2170) for the ITR14's normal tax not yet charged, dated the year end. A payment to SARS is DR 2170, so the payable ends at the tax still owed (a debit is tax paid ahead). Posts once per year end: a second post posts only a change in the tax. Refused when the business is not taxed on its own return or the return states no tax. Needs sars:approve.", "operationId": "postApiSarsIt14CurrentTax", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsIt14SubmitRequest" }, "example": { "year": 2027 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSarsIt14CurrentTaxResponse" }, "example": { "yearEnd": "2027-02-28", "normalTax": 270000.0, "paidToSars": 200000.0, "charged": 270000.0, "movement": 0.0, "payable": 70000.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/it14/submit": { "post": { "tags": [ "SARS returns" ], "summary": "Note the ITR14 as filed.", "operationId": "postApiSarsIt14Submit", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsIt14SubmitRequest" }, "example": { "year": 2027 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsIrp6SubmitResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsIrp6SubmitResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/irp6": { "get": { "tags": [ "SARS returns" ], "summary": "The provisional tax estimate for a period (1, 2, or 3 for the voluntary top-up after year end). `estimate` is the taxable income you mean to file (default: the prepared figure); the first period warns when the estimate is below the basic amount (para 19(1)(c)); the second period is tested as SARS will test it, against the basic amount and 90% (80% above R1 million) of the year as projected, with the required minimum and the estimated under-estimation penalty (20% of the tax on the minimum less the tax paid to SARS by the year end). `alreadyPaid` is money paid to SARS, not IRP6s noted as filed.", "operationId": "getApiSarsIrp6", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2027" }, { "name": "period", "in": "query", "required": false, "description": "Which of a return's periods this is. Refused rather than defaulted.", "schema": { "type": "integer" }, "example": "2" }, { "name": "basis", "in": "query", "required": false, "schema": { "type": "string" }, "example": "annualised" }, { "name": "estimate", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "150000" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taxYearLabel": { "type": "string" }, "periodNumber": { "type": "integer" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "taxableIncomeToDate": { "type": "number" }, "estimatedAnnualTaxableIncome": { "type": "number" }, "estimatedAnnualTax": { "type": "number" }, "alreadyPaid": { "type": "number" }, "periodPayment": { "type": "number" }, "estimate": { "type": "boolean" } } }, "example": { "taxYearLabel": "2027", "periodNumber": 1, "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "taxableIncomeToDate": 1305.0, "estimatedAnnualTaxableIncome": 1305.0, "estimatedAnnualTax": 1305.0, "alreadyPaid": 1.0, "periodPayment": 1.0, "estimate": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/irp6/submit": { "post": { "tags": [ "SARS returns" ], "summary": "Note the IRP6 as filed — period 1, 2 or 3 (the voluntary top-up), on the taxable income in `estimate` (default: the prepared figure).", "operationId": "postApiSarsIrp6Submit", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer" }, "period": { "type": "integer" }, "basis": { "type": "string" }, "estimate": { "type": "number" } } }, "example": { "year": 2027, "period": 1, "basis": "invoice", "estimate": 150000.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsIrp6SubmitResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsIrp6SubmitResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/irp6/basic-amount": { "put": { "tags": [ "SARS returns" ], "summary": "Record the IRP6 basic amount for a year of assessment: the taxable income on your latest SARS assessment, and which year that assessment was for. The second-period under-estimation test reads it. Answers with that year's second-period estimate. Needs sars:edit.", "operationId": "putApiSarsIrp6BasicAmount", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer" }, "basicAmount": { "type": "number" }, "assessedYear": { "type": "integer" } } }, "example": { "year": 2027, "basicAmount": 200000.0, "assessedYear": 2026 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taxYearLabel": { "type": "string" }, "periodNumber": { "type": "integer" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "taxableIncomeToDate": { "type": "number" }, "estimatedAnnualTaxableIncome": { "type": "number" }, "estimatedAnnualTax": { "type": "number" }, "alreadyPaid": { "type": "number" }, "periodPayment": { "type": "number" }, "estimate": { "type": "boolean" }, "basis": { "type": "string" }, "basicAmount": { "type": "number" }, "basicAmountAssessedYear": { "type": "integer" }, "filedEstimate": { "type": "number" }, "requiredMinimum": { "type": "number" }, "testName": { "type": "string" }, "passesTest": { "type": "boolean" }, "estimatedPenalty": { "type": "number" }, "issues": { "type": "array", "items": { "type": "object" } } } }, "example": { "taxYearLabel": "2027", "periodNumber": 2, "periodStart": "2026-03-01", "periodEnd": "2027-02-28", "taxableIncomeToDate": 87500.0, "estimatedAnnualTaxableIncome": 150000.0, "estimatedAnnualTax": 40500.0, "alreadyPaid": 0.0, "periodPayment": 40500.0, "estimate": true, "basis": "annualised", "basicAmount": 200000.0, "basicAmountAssessedYear": 2026, "filedEstimate": 150000.0, "requiredMinimum": 135000.0, "testName": "ninety_percent_or_basic", "passesTest": true, "estimatedPenalty": 0.0, "issues": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars-submissions": { "get": { "tags": [ "SARS returns" ], "summary": "The filing register across every tax type.", "operationId": "getApiSarsSubmissions", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Restrict to one type. Matched case-insensitively; an unrecognised value is refused.", "schema": { "type": "string" }, "example": "vat201" }, { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "filed" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiSarsSubmissionsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "submissionType": "EMP201", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "totalPaye": 12400.0, "totalUif": 1062.72, "totalSdl": 890.0, "totalEti": 500.0, "totalPayable": 13852.72, "totalDue": 13852.72, "status": "sent", "referenceNumber": "INV-0001", "paymentReferenceNumber": "7012345676LC2609000", "submittedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "SARS returns" ], "summary": "Add a filing record by hand.", "operationId": "postApiSarsSubmissions", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsSubmissionsRequest" }, "example": { "submissionType": "VAT201", "periodStart": "2026-07-01", "periodEnd": "2026-08-31" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsSubmissionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsSubmissionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars-submissions/{id}": { "get": { "tags": [ "SARS returns" ], "summary": "One filing record.", "operationId": "getApiSarsSubmissionsById", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsSubmissionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsSubmissionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "SARS returns" ], "summary": "Correct a filing record.", "operationId": "putApiSarsSubmissionsById", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsSubmissionsRequest" }, "example": { "submissionType": "VAT201", "periodStart": "2026-07-01", "periodEnd": "2026-08-31" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsSubmissionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsSubmissionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars-submissions/{id}/submit": { "post": { "tags": [ "SARS returns" ], "summary": "Mark a prepared return as filed. Optionally keep what eFiling issued: sarsReference, filedOn, and the payment (paidOn with paidAmount); a date before the period ended or in the future is refused (400).", "operationId": "postApiSarsSubmissionsByIdSubmit", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentReferenceNumber": { "type": "string" }, "sarsReference": { "type": "string" }, "filedOn": { "type": "string", "format": "date" }, "paidOn": { "type": "string", "format": "date" }, "paidAmount": { "type": "number" } } }, "example": { "paymentReferenceNumber": "7012345676LC2609000", "sarsReference": "EFL-2026-0007", "filedOn": "2026-09-03", "paidOn": "2026-09-03", "paidAmount": 13852.72 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsSubmissionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsSubmissionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars-submissions/{id}/payment-reference": { "put": { "tags": [ "SARS returns" ], "summary": "Record the payment reference number SARS issued for a filed EMP201.", "operationId": "putApiSarsSubmissionsByIdPaymentReference", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentReferenceNumber": { "type": "string" } } }, "example": { "paymentReferenceNumber": "7012345676LC2609000" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsSubmissionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsSubmissionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars-submissions/{id}/filing-details": { "put": { "tags": [ "SARS returns" ], "summary": "Keep what eFiling issued for a return already noted as filed: SARS's reference, the day it was filed, and the payment (paidOn with paidAmount). Replaces the four; a blank part clears it. A date before the period ended or in the future is refused (400); a return not yet filed is refused (409).", "operationId": "putApiSarsSubmissionsByIdFilingDetails", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sarsReference": { "type": "string" }, "filedOn": { "type": "string", "format": "date" }, "paidOn": { "type": "string", "format": "date" }, "paidAmount": { "type": "number" } } }, "example": { "sarsReference": "EFL-2026-0007", "filedOn": "2026-09-03", "paidOn": "2026-09-03", "paidAmount": 13852.72 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "submissionType": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "totalPaye": { "type": "number" }, "totalUif": { "type": "number" }, "totalSdl": { "type": "number" }, "totalEti": { "type": "number" }, "totalPayable": { "type": "number" }, "totalDue": { "type": "number" }, "status": { "type": "string" }, "referenceNumber": { "type": "string" }, "submittedAt": { "type": "string" }, "createdAt": { "type": "string" }, "sarsReference": { "type": "string" }, "filedOn": { "type": "string", "format": "date" }, "paidOn": { "type": "string", "format": "date" }, "paidAmount": { "type": "number" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "submissionType": "EMP201", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "totalPaye": 12400.0, "totalUif": 1062.72, "totalSdl": 890.0, "totalEti": 500.0, "totalPayable": 13852.72, "totalDue": 13852.72, "status": "sent", "referenceNumber": "INV-0001", "submittedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z", "sarsReference": "EFL-2026-0007", "filedOn": "2026-09-03", "paidOn": "2026-09-03", "paidAmount": 13852.72 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars-submissions/{id}/correction": { "post": { "tags": [ "SARS returns" ], "summary": "Note the request for correction (RFC) of a filed EMP201: the filed row takes the payslips' figures and the old ones are kept.", "operationId": "postApiSarsSubmissionsByIdCorrection", "description": "Requires the `sars:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string" } } }, "example": { "reference": "RFC-2026-0912" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsSubmissionsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "submissionType": "EMP201", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "totalPaye": 12900.0, "totalUif": 1062.72, "totalSdl": 890.0, "totalEti": 500.0, "totalPayable": 14352.72, "totalDue": 14352.72, "status": "sent", "referenceNumber": "INV-0001", "paymentReferenceNumber": "7012345676LC2609000", "submittedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars-submissions/emp201/{periodId}": { "get": { "tags": [ "SARS returns" ], "summary": "The EMP201 figures for a payroll period.", "operationId": "getApiSarsSubmissionsEmp201ByPeriodId", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "periodId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollPeriodsByIdEmp201Response" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollPeriodsByIdEmp201ResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars-submissions/emp501": { "get": { "tags": [ "SARS returns" ], "summary": "The EMP501 reconciliation figures.", "operationId": "getApiSarsSubmissionsEmp501", "description": "Requires the `sars:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "sars:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "taxYear", "in": "query", "required": false, "description": "South African year of assessment, named by the year it ENDS in: 2027 is 1 March 2026 to 28 February 2027. A year Ledgr holds no tables for is refused outright rather than served from the nearest one.", "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollEmp501Response" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollEmp501ResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/employees": { "get": { "tags": [ "Payroll" ], "summary": "Employees with their statutory fields.", "operationId": "getApiEmployees", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" }, { "name": "includeLeavers", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiEmployeesResponse" } }, "example": [ { "documentLanguage": "text", "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "firstName": "Karoo Fresh Holdings Ltd", "lastName": "Karoo Fresh Holdings Ltd", "idNumber": "INV-0001", "passportNumber": "INV-0001", "passportCountry": "South Africa", "addressLine1": "12 Long Street", "addressLine2": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "addressCountry": "South Africa", "asylumPermitNumber": "INV-0001", "natureOfPerson": "text", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "dateOfBirth": "1988-04-12", "employmentType": "standard", "contractorWorksAtPremises": true, "contractorIsSupervised": true, "contractorHasThreeEmployees": true, "contractorNonResident": true, "irp30Number": "INV-0001", "irp30ValidTo": "2026-09-30", "pspRegistrationType": "standard", "pspRegistrationNumber": "2021/123456/07", "noOtherEmployerDeclaration": true, "startDate": "2026-09-01", "endDate": "2026-09-30", "terminationReason": "Budget deferred to the next financial year.", "terminated": false, "jobTitle": "Karoo Fresh Holdings Ltd", "department": "Sales", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "bankName": "FNB", "bankAccountNumber": "62012345678", "bankBranchCode": "250655", "bankAccountType": "current", "paymentMethod": "eft", "secondBankName": "FNB", "secondBankAccountNumber": "62012345678", "secondBankBranchCode": "250655", "secondBankAccountType": "standard", "splitAmount": 10005.0, "splitPercent": 15.0, "minimumWageExemption": "text", "minimumWageExemptionUntil": "2026-09-30", "learnershipRegistrationNumber": "2021/123456/07", "learnershipNqfLevel": 1, "learnershipStart": "2026-09-01", "learnershipEnd": "2026-09-30", "learnershipDisability": true, "learnershipCompletedOn": "2026-09-01", "learnershipCreditsEarned": 1, "epwpWorker": true, "prescribedOfficer": false, "taxNumber": "9012345678", "uifLiable": true, "payFrequency": "MONTHLY", "basicSalary": 1.0, "travelAllowance": 1.0, "pensionContribution": 1.0, "medicalAidContribution": 1.0, "medicalAidMembers": 1, "travelInclusionRate": 15.0, "openingYtdTaxYearEnd": 1, "openingYtdRemuneration": 1.0, "openingYtdPaye": 1.0, "openingYtdAnnualPayments": 1.0, "openingYtdPayeOnAnnualPayments": 1.0, "leaveBalances": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leaveType": "annual", "balanceDays": 10005.0, "takenDays": 1.0 } ], "leaveDaysPerWeek": 5, "leaveWorksSundays": false, "leaveWeekdays": [ 1, 2, 3, 4, 5 ], "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Payroll" ], "summary": "Create an employee. default_charge_rate and default_cost_rate live on the user record and fill in job-card labour — null means \"not set\" rather than zero, and the reports say so rather than showing a flattering 100% margin.", "operationId": "postApiEmployees", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "employeeNumber": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "idNumber": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date" }, "employmentType": { "type": "string" }, "contractorWorksAtPremises": { "type": "null" }, "contractorIsSupervised": { "type": "null" }, "contractorHasThreeEmployees": { "type": "null" }, "contractorNonResident": { "type": "null" }, "irp30Number": { "type": "null" }, "irp30ValidTo": { "type": "null" }, "pspRegistrationType": { "type": "null" }, "pspRegistrationNumber": { "type": "null" }, "noOtherEmployerDeclaration": { "type": "boolean" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "jobTitle": { "type": "string" }, "department": { "type": "string" }, "costCentreId": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "bankAccountNumber": { "type": "string" }, "bankName": { "type": "string" }, "bankBranchCode": { "type": "string" }, "bankAccountType": { "type": "string" }, "paymentMethod": { "type": "string" }, "secondBankName": { "type": "string" }, "secondBankAccountNumber": { "type": "string" }, "secondBankBranchCode": { "type": "string" }, "secondBankAccountType": { "type": "string" }, "splitAmount": { "type": "number" }, "splitPercent": { "type": "null" }, "learnershipRegistrationNumber": { "type": "null" }, "learnershipNqfLevel": { "type": "null" }, "learnershipStart": { "type": "null" }, "learnershipEnd": { "type": "null" }, "learnershipDisability": { "type": "boolean" }, "learnershipCompletedOn": { "type": "null" }, "learnershipCreditsEarned": { "type": "null" }, "epwpWorker": { "type": "boolean" }, "prescribedOfficer": { "type": "boolean" }, "taxNumber": { "type": "string" }, "uifLiable": { "type": "boolean" }, "payFrequency": { "type": "string" }, "basicSalary": { "type": "number" }, "payBasis": { "type": "string" }, "hourlyRate": { "type": "number" }, "payTemplateId": { "type": "string" }, "ordinaryHoursWeekly": { "type": "number" }, "ordinaryDaysWeekly": { "type": "integer" }, "ordinaryWeekdays": { "type": "array", "items": { "type": "integer" } }, "ordinarilyWorksSundays": { "type": "boolean" }, "travelAllowance": { "type": "number" }, "pensionContribution": { "type": "number" }, "medicalAidContribution": { "type": "number" }, "medicalAidMembers": { "type": "integer" }, "travelInclusionRate": { "type": "number" }, "natureOfPerson": { "type": "string" }, "passportNumber": { "type": "string" }, "passportCountry": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "addressCountry": { "type": "string" }, "asylumPermitNumber": { "type": "string" }, "userId": { "type": "string" }, "etiExclusion": { "type": "string" }, "etiMinimumWageMonthly": { "type": "number" }, "etiNoWageRegulatingMeasure": { "type": "boolean" }, "etiMonthsClaimedBeforeLedgr": { "type": "integer" }, "openingYtdTaxYearEnd": { "type": "integer" }, "openingYtdRemuneration": { "type": "number" }, "openingYtdPaye": { "type": "number" }, "openingYtdAnnualPayments": { "type": "number" }, "openingYtdPayeOnAnnualPayments": { "type": "number" }, "minimumWageExemption": { "type": "string" }, "minimumWageExemptionUntil": { "type": "string", "format": "date" }, "documentLanguage": { "type": "string" } } }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "firstName": "Thandi", "lastName": "Mokoena", "idNumber": "INV-0001", "dateOfBirth": "1988-04-12", "employmentType": "PERMANENT", "contractorWorksAtPremises": null, "contractorIsSupervised": null, "contractorHasThreeEmployees": null, "contractorNonResident": null, "irp30Number": null, "irp30ValidTo": null, "pspRegistrationType": null, "pspRegistrationNumber": null, "noOtherEmployerDeclaration": false, "startDate": "2026-09-01", "endDate": "2026-09-30", "jobTitle": "Karoo Fresh Holdings Ltd", "department": "Sales", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "bankAccountNumber": "62012345678", "bankName": "FNB", "bankBranchCode": "250655", "bankAccountType": "current", "paymentMethod": "SPLIT", "secondBankName": "Capitec", "secondBankAccountNumber": "1234567890", "secondBankBranchCode": "470010", "secondBankAccountType": "savings", "splitAmount": 1000.0, "splitPercent": null, "learnershipRegistrationNumber": null, "learnershipNqfLevel": null, "learnershipStart": null, "learnershipEnd": null, "learnershipDisability": false, "learnershipCompletedOn": null, "learnershipCreditsEarned": null, "epwpWorker": false, "prescribedOfficer": false, "taxNumber": "9012345678", "uifLiable": true, "payFrequency": "MONTHLY", "basicSalary": 1.0, "payBasis": "salary", "hourlyRate": 15.0, "payTemplateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ordinaryHoursWeekly": 3.0, "ordinaryDaysWeekly": 5, "ordinaryWeekdays": [ 1, 2, 3, 4, 5 ], "ordinarilyWorksSundays": false, "travelAllowance": 1.0, "pensionContribution": 1.0, "medicalAidContribution": 1.0, "medicalAidMembers": 1, "travelInclusionRate": 15.0, "natureOfPerson": "A", "passportNumber": "INV-0001", "passportCountry": "South Africa", "addressLine1": "4 Kloof Street", "addressLine2": "Tamboerskloof", "city": "Cape Town", "postalCode": "8001", "addressCountry": "ZA", "asylumPermitNumber": "CTRIMO001232019", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "etiExclusion": "Connected person to the employer", "etiMinimumWageMonthly": 1.0, "etiNoWageRegulatingMeasure": false, "etiMonthsClaimedBeforeLedgr": 1, "openingYtdTaxYearEnd": 1, "openingYtdRemuneration": 1.0, "openingYtdPaye": 1.0, "openingYtdAnnualPayments": 1.0, "openingYtdPayeOnAnnualPayments": 1.0, "minimumWageExemption": "NMW-EX-2026-014", "minimumWageExemptionUntil": "2027-02-28", "documentLanguage": "af" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiEmployeesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiEmployeesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/employees/{id}": { "get": { "tags": [ "Payroll" ], "summary": "One employee.", "operationId": "getApiEmployeesById", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiEmployeesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiEmployeesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Payroll" ], "summary": "Update an employee.", "operationId": "putApiEmployeesById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "addressCountry": { "type": "string" }, "asylumPermitNumber": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "idNumber": { "type": "string" }, "employeeNumber": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "dateOfBirth": { "type": "string", "format": "date" }, "payBasis": { "type": "string" }, "contactId": { "type": "string" }, "employmentType": { "type": "string" }, "contractorWorksAtPremises": { "type": "null" }, "contractorIsSupervised": { "type": "null" }, "contractorHasThreeEmployees": { "type": "null" }, "contractorNonResident": { "type": "null" }, "irp30Number": { "type": "null" }, "irp30ValidTo": { "type": "null" }, "pspRegistrationType": { "type": "null" }, "pspRegistrationNumber": { "type": "null" }, "noOtherEmployerDeclaration": { "type": "null" }, "endDate": { "type": "string", "format": "date" }, "terminationReason": { "type": "string" }, "jobTitle": { "type": "string" }, "department": { "type": "string" }, "costCentreId": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "bankAccountNumber": { "type": "string" }, "bankName": { "type": "string" }, "bankBranchCode": { "type": "string" }, "bankAccountType": { "type": "string" }, "paymentMethod": { "type": "string" }, "secondBankName": { "type": "string" }, "secondBankAccountNumber": { "type": "string" }, "secondBankBranchCode": { "type": "string" }, "secondBankAccountType": { "type": "string" }, "splitAmount": { "type": "number" }, "splitPercent": { "type": "null" }, "learnershipRegistrationNumber": { "type": "null" }, "learnershipNqfLevel": { "type": "null" }, "learnershipStart": { "type": "null" }, "learnershipEnd": { "type": "null" }, "learnershipDisability": { "type": "boolean" }, "learnershipCompletedOn": { "type": "null" }, "learnershipCreditsEarned": { "type": "null" }, "epwpWorker": { "type": "boolean" }, "prescribedOfficer": { "type": "boolean" }, "taxNumber": { "type": "string" }, "uifLiable": { "type": "boolean" }, "payFrequency": { "type": "string" }, "basicSalary": { "type": "number" }, "hourlyRate": { "type": "number" }, "payTemplateId": { "type": "string" }, "ordinaryHoursWeekly": { "type": "number" }, "ordinaryDaysWeekly": { "type": "integer" }, "ordinaryWeekdays": { "type": "array", "items": { "type": "integer" } }, "ordinarilyWorksSundays": { "type": "boolean" }, "travelAllowance": { "type": "number" }, "pensionContribution": { "type": "number" }, "medicalAidContribution": { "type": "number" }, "medicalAidMembers": { "type": "integer" }, "travelInclusionRate": { "type": "number" }, "natureOfPerson": { "type": "string" }, "passportNumber": { "type": "string" }, "passportCountry": { "type": "string" }, "userId": { "type": "string" }, "etiExclusion": { "type": "string" }, "etiMinimumWageMonthly": { "type": "number" }, "etiNoWageRegulatingMeasure": { "type": "boolean" }, "etiMonthsClaimedBeforeLedgr": { "type": "integer" }, "openingYtdTaxYearEnd": { "type": "integer" }, "openingYtdRemuneration": { "type": "number" }, "openingYtdPaye": { "type": "number" }, "openingYtdAnnualPayments": { "type": "number" }, "openingYtdPayeOnAnnualPayments": { "type": "number" }, "minimumWageExemption": { "type": "string" }, "minimumWageExemptionUntil": { "type": "string", "format": "date" }, "basicEffectiveFrom": { "type": "string", "format": "date" }, "documentLanguage": { "type": "string" } } }, "example": { "addressLine1": "4 Kloof Street", "addressLine2": "Tamboerskloof", "city": "Cape Town", "postalCode": "8001", "addressCountry": "ZA", "asylumPermitNumber": "CTRIMO001232019", "firstName": "Thandi", "lastName": "Mokoena", "idNumber": "8506155009085", "employeeNumber": "EMP-0042", "startDate": "2026-03-01", "dateOfBirth": "1985-06-15", "payBasis": "salary", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employmentType": "standard", "contractorWorksAtPremises": null, "contractorIsSupervised": null, "contractorHasThreeEmployees": null, "contractorNonResident": null, "irp30Number": null, "irp30ValidTo": null, "pspRegistrationType": null, "pspRegistrationNumber": null, "noOtherEmployerDeclaration": null, "endDate": "2026-09-30", "terminationReason": "Budget deferred to the next financial year.", "jobTitle": "Karoo Fresh Holdings Ltd", "department": "Sales", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "bankAccountNumber": "62012345678", "bankName": "FNB", "bankBranchCode": "250655", "bankAccountType": "standard", "paymentMethod": "SPLIT", "secondBankName": "Capitec", "secondBankAccountNumber": "1234567890", "secondBankBranchCode": "470010", "secondBankAccountType": "savings", "splitAmount": 1000.0, "splitPercent": null, "learnershipRegistrationNumber": null, "learnershipNqfLevel": null, "learnershipStart": null, "learnershipEnd": null, "learnershipDisability": false, "learnershipCompletedOn": null, "learnershipCreditsEarned": null, "epwpWorker": false, "prescribedOfficer": false, "taxNumber": "9012345678", "uifLiable": true, "payFrequency": "monthly", "basicSalary": 1.0, "hourlyRate": 15.0, "payTemplateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ordinaryHoursWeekly": 3.0, "ordinaryDaysWeekly": 5, "ordinaryWeekdays": [ 1, 2, 3, 4, 5 ], "ordinarilyWorksSundays": false, "travelAllowance": 1.0, "pensionContribution": 1.0, "medicalAidContribution": 1.0, "medicalAidMembers": 1, "travelInclusionRate": 15.0, "natureOfPerson": "A", "passportNumber": "INV-0001", "passportCountry": "South Africa", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "etiExclusion": "Connected person to the employer", "etiMinimumWageMonthly": 1.0, "etiNoWageRegulatingMeasure": true, "etiMonthsClaimedBeforeLedgr": 1, "openingYtdTaxYearEnd": 1, "openingYtdRemuneration": 1.0, "openingYtdPaye": 1.0, "openingYtdAnnualPayments": 1.0, "openingYtdPayeOnAnnualPayments": 1.0, "minimumWageExemption": "NMW-EX-2026-014", "minimumWageExemptionUntil": "2027-02-28", "basicEffectiveFrom": "2026-03-01", "documentLanguage": "af" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiEmployeesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiEmployeesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Payroll" ], "summary": "Terminate an employee: ends the employment on endDate and keeps the record, so the final month is paid to the last day and owed annual leave is paid out; notice=paid pays the notice period in lieu (BCEA s38), and a retrenchment adds severance taxed by its lump-sum directive. With capturedInError=true the record is deleted instead, refused once any payslip exists.", "operationId": "deleteApiEmployeesById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "reason", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Duplicate" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "capturedInError", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "false" }, { "name": "notice", "in": "query", "required": false, "schema": { "type": "string" }, "example": "worked" } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/employees/{id}/payslips": { "get": { "tags": [ "Payroll" ], "summary": "One employee's payslip history.", "operationId": "getApiEmployeesByIdPayslips", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayslipsByIdResponse" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiEmployeesByIdPayslipsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/employees/{id}/leave-balances": { "get": { "tags": [ "Payroll" ], "summary": "BCEA balances — 15 days annual, 30 days sick over a three-year cycle, three days family responsibility.", "operationId": "getApiEmployeesByIdLeaveBalances", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiEmployeesResponseLeaveBalancesItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leaveType": "annual", "balanceDays": 10005.0, "takenDays": 1.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/employees/{id}/irp5": { "get": { "tags": [ "Payroll" ], "summary": "One employee's IRP5 as data. payPeriodsWorked is code 3210 as the certificate states it, a part period as its fraction (6.5 for a leaver of 15 September); monthsWorked is the same count rounded to a whole number and is kept only for compatibility.", "operationId": "getApiEmployeesByIdIrp5", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "taxYear", "in": "query", "required": false, "description": "South African year of assessment, named by the year it ENDS in: 2027 is 1 March 2026 to 28 February 2027. A year Ledgr holds no tables for is refused outright rather than served from the nearest one.", "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "employeeNumber": { "type": "string" }, "taxNumber": { "type": "string" }, "idNumber": { "type": "string" }, "taxYear": { "type": "string" }, "certificateNumber": { "type": "string" }, "certificateType": { "type": "string" }, "grossRemuneration": { "type": "number" }, "payeDeducted": { "type": "number" }, "uifTotal": { "type": "number" }, "sdl": { "type": "number" }, "pensionTotal": { "type": "number" }, "medicalTotal": { "type": "number" }, "providentTotal": { "type": "number" }, "retirementAnnuityTotal": { "type": "number" }, "medicalTaxCredit": { "type": "number" }, "additionalMedicalCredit": { "type": "number" }, "severanceBenefit": { "type": "number" }, "lumpSumTax": { "type": "number" }, "eti": { "type": "number" }, "totalTaxSdlUif": { "type": "number" }, "employerRetirementBenefit": { "type": "number" }, "employerMedicalBenefit": { "type": "number" }, "monthsWorked": { "type": "integer" }, "payPeriodsWorked": { "type": "number" }, "periodsInYear": { "type": "integer" }, "takeOnIncluded": { "type": "boolean" }, "takeOnGrossRemuneration": { "type": "number" }, "takeOnPaye": { "type": "number" }, "takeOnSourceLabel": { "type": "string" } } }, "example": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "employeeNumber": "INV-0001", "taxNumber": "9012345678", "idNumber": "INV-0001", "taxYear": "2027", "certificateNumber": "INV-0001", "certificateType": "standard", "grossRemuneration": 1.0, "payeDeducted": 1.0, "uifTotal": 10005.0, "sdl": 1.0, "pensionTotal": 10005.0, "medicalTotal": 10005.0, "providentTotal": 10005.0, "retirementAnnuityTotal": 10005.0, "medicalTaxCredit": 1305.0, "additionalMedicalCredit": 1.0, "severanceBenefit": 1.0, "lumpSumTax": 1305.0, "eti": 1.0, "totalTaxSdlUif": 1305.0, "employerRetirementBenefit": 1.0, "employerMedicalBenefit": 1.0, "monthsWorked": 1, "payPeriodsWorked": 1.0, "periodsInYear": 12, "takeOnIncluded": false, "takeOnGrossRemuneration": 1.0, "takeOnPaye": 1.0, "takeOnSourceLabel": "Karoo Fresh Holdings Ltd" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/employees/{id}/irp5.pdf": { "get": { "tags": [ "Payroll" ], "summary": "The same certificate as a PDF - or, until it may be delivered (the year's annual EMP501 noted as filed, or the employee left in it), a tax-year-to-date statement with no certificate number. For an employee ended as deceased it is headed as issued to the executor of the estate, who is owed it within 14 days of the death.", "operationId": "getApiEmployeesByIdIrp5.pdf", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "taxYear", "in": "query", "required": false, "description": "South African year of assessment, named by the year it ENDS in: 2027 is 1 March 2026 to 28 February 2027. A year Ledgr holds no tables for is refused outright rather than served from the nearest one.", "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods": { "get": { "tags": [ "Payroll" ], "summary": "Payroll periods and their state.", "operationId": "getApiPayrollPeriods", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollPeriodsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodType": "2026-09", "startDate": "2026-09-01", "endDate": "2026-09-30", "payDate": "2026-09-01", "status": "sent", "grossTotal": 10005.0, "payeTotal": 10005.0, "uifTotal": 10005.0, "sdlTotal": 10005.0, "nettTotal": 8700.0, "employeeCount": 3, "uifEmployeeTotal": 10005.0, "uifEmployerTotal": 10005.0, "pensionTotal": 10005.0, "medicalTotal": 10005.0, "thirdPartyDeductionsTotal": 10005.0, "employerRetirementTotal": 10005.0, "employerMedicalTotal": 10005.0, "employeeDeductionsTotal": 10005.0, "employerContributionsTotal": 10005.0, "costToCompanyTotal": 10005.0, "deductionsReconcile": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Payroll" ], "summary": "Open a period.", "operationId": "postApiPayrollPeriods", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPeriodsRequest" }, "example": { "periodType": "MONTHLY", "startDate": "2026-09-01", "endDate": "2026-09-30", "payDate": "2026-09-25" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPeriodsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPeriodsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}": { "get": { "tags": [ "Payroll" ], "summary": "One period with its totals.", "operationId": "getApiPayrollPeriodsById", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPeriodsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPeriodsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Payroll" ], "summary": "Change a period's dates before it is run.", "operationId": "putApiPayrollPeriodsById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPeriodsRequest" }, "example": { "periodType": "MONTHLY", "startDate": "2026-09-01", "endDate": "2026-09-30", "payDate": "2026-09-26" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPeriodsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPeriodsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Payroll" ], "summary": "Delete an unrun period.", "operationId": "deleteApiPayrollPeriodsById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/run": { "post": { "tags": [ "Payroll" ], "summary": "Calculate the period — PAYE, UIF at 1% capped at R177.12 each side, SDL at 1%, ETI, deductions and fringe benefits.", "operationId": "postApiPayrollPeriodsByIdRun", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "$ref": "#/components/schemas/PostApiPayrollPeriodsResponse" }, "payslipsCreated": { "type": "integer" }, "alreadyRun": { "type": "boolean" } } }, "example": { "period": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodType": "2026-09", "startDate": "2026-09-01", "endDate": "2026-09-30", "payDate": "2026-09-01", "status": "sent", "grossTotal": 10005.0, "payeTotal": 10005.0, "uifTotal": 10005.0, "sdlTotal": 10005.0, "nettTotal": 8700.0, "employeeCount": 3, "uifEmployeeTotal": 10005.0, "uifEmployerTotal": 10005.0, "pensionTotal": 10005.0, "medicalTotal": 10005.0, "thirdPartyDeductionsTotal": 10005.0, "employerRetirementTotal": 10005.0, "employerMedicalTotal": 10005.0, "employeeDeductionsTotal": 10005.0, "employerContributionsTotal": 10005.0, "costToCompanyTotal": 10005.0, "deductionsReconcile": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" }, "payslipsCreated": 1, "alreadyRun": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/inputs": { "get": { "tags": [ "Payroll" ], "summary": "The period's pay inputs — units and one-off amounts typed or fed for each employee and earning type — a page at a time (`page`, `limit`, optional `employeeId`). `editable` is false once the run is approved or paid.", "operationId": "getApiPayrollPeriodsByIdInputs", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "employeeId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "8b2d1e44-0c9a-4f71-b6de-5a3c2f1e9d07" }, { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "200" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollPeriodsByIdInputsResponseItemsItem" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" }, "editable": { "type": "boolean" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeName": "Overtime", "units": 1.0, "amount": 10005.0, "sourceKind": "standard", "sourceRef": "INV-0001", "note": "Budget deferred to the next financial year." } ], "total": 42, "page": 1, "limit": 50, "totalPages": 1, "editable": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Payroll" ], "summary": "Hold manual pay inputs for the period: units for a per-unit earning, an amount for a fixed one, both null to clear. A re-run of the period pays them. Refused with 409 once the run is approved or paid.", "operationId": "putApiPayrollPeriodsByIdInputs", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inputs": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string" }, "earningTypeId": { "type": "string" }, "units": { "type": "number" }, "note": { "type": "string" }, "weekStart": { "type": "string", "format": "date" } } } } } }, "example": { "inputs": [ { "employeeId": "8b2d1e44-0c9a-4f71-b6de-5a3c2f1e9d07", "earningTypeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "units": 5.0, "note": "Night shifts, week 2", "weekStart": "2026-09-07" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "written": { "type": "integer" }, "cleared": { "type": "integer" }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollPeriodsByIdInputsResponseItemsItem" } } } }, "example": { "written": 1, "cleared": 1, "inputs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeName": "Overtime", "units": 1.0, "amount": 10005.0, "sourceKind": "standard", "sourceRef": "INV-0001", "note": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/inputs/pull/logistics": { "post": { "tags": [ "Payroll" ], "summary": "Pull from Logistics: every run completed within the period, in South African time and in the period's company, credited as hours worked to the driver and the assistant through their payroll links — Sunday and public-holiday hours as their own kinds. Idempotent: a second pull holds what Logistics says now. `skipped` names what could not be counted. Refused with 409 once the run is approved or paid.", "operationId": "postApiPayrollPeriodsByIdInputsPullLogistics", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPeriodsByIdInputsPullJobsResponse" }, "example": { "source": "referral", "counted": 3, "people": 1, "hours": 3.0, "skipped": [ "text" ], "removed": 0, "inputs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeName": "Overtime", "units": 1.0, "amount": 10005.0, "sourceKind": "standard", "sourceRef": "INV-0001", "note": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/inputs/pull/time": { "post": { "tags": [ "Payroll" ], "summary": "Pull from Time Tracking: every approved time entry whose work date falls in the period, credited as ordinary hours to the employee its user is linked to in the period's company. A billed hour is still paid. Idempotent; an entry un-approved since the last pull is taken off and counted in `removed`. A user on two companies' payrolls, or on none, is named in `skipped` and not counted. Refused with 409 once the run is approved or paid.", "operationId": "postApiPayrollPeriodsByIdInputsPullTime", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPeriodsByIdInputsPullJobsResponse" }, "example": { "source": "time", "counted": 3, "people": 1, "hours": 3.0, "skipped": [ "text" ], "removed": 0, "inputs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeName": "Overtime", "units": 1.0, "amount": 10005.0, "sourceKind": "standard", "sourceRef": "INV-0001", "note": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/inputs/pull/shift": { "post": { "tags": [ "Payroll" ], "summary": "Pull from the shift register: every shift whose day falls in the period, as hours in the category its date says (Sunday, public holiday on an ordinary day or not, else normal) for the run to settle by the week, plus one unit of each per-unit allowance the shift earns. Idempotent; a shift deleted since the last pull is taken off and counted in `removed`. Refused with 409 once the run is approved or paid.", "operationId": "postApiPayrollPeriodsByIdInputsPullShift", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPeriodsByIdInputsPullJobsResponse" }, "example": { "source": "shift", "counted": 3, "people": 1, "hours": 3.0, "skipped": [ "text" ], "removed": 0, "inputs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeName": "Overtime", "units": 1.0, "amount": 10005.0, "sourceKind": "standard", "sourceRef": "INV-0001", "note": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/shift-register": { "get": { "tags": [ "Payroll" ], "summary": "The shift register for a window of at most 62 days, optionally one employee: each day worked, its hours, the category its date is paid in and the allowances it earns.", "operationId": "getApiPayrollShiftRegister", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "employeeId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiPayrollShiftRegisterResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "workDate": "2026-09-24", "hours": 12.0, "category": "ph_worked_ordinary_day", "allowanceTypeIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "note": "Night shift at the Midrand site." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Payroll" ], "summary": "Record one employee's day: hours (more than 0, at most 24) and the per-unit allowances the shift earns. Saving the same day again replaces it. Refused for a day the employee is not employed on, or an allowance that is not one of the tenant's per-unit earnings.", "operationId": "putApiPayrollShiftRegister", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employeeId": { "type": "string" }, "workDate": { "type": "string", "format": "date" }, "hours": { "type": "number" }, "allowanceTypeIds": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } } }, "example": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workDate": "2026-09-24", "hours": 12.0, "allowanceTypeIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "note": "Night shift at the Midrand site." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiPayrollShiftRegisterResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "workDate": "2026-09-24", "hours": 12.0, "category": "ph_worked_ordinary_day", "allowanceTypeIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "note": "Night shift at the Midrand site." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/shift-register/{id}": { "delete": { "tags": [ "Payroll" ], "summary": "Remove a shift from the register. A period already pulled loses it on its next pull.", "operationId": "deleteApiPayrollShiftRegisterById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/employees/{id}/equity": { "get": { "tags": [ "Payroll" ], "summary": "An employee's Employment Equity categories — race, gender, disability, nationality and occupational level, each one of the EEA2's own; null is not recorded. Special personal information (POPIA s26): needs equity:view, which payroll:view does not grant, and every read is written to the audit log by who and which employee, never the values.", "operationId": "getApiEmployeesByIdEquity", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiEmployeesByIdEquityResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiEmployeesByIdEquityResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Payroll" ], "summary": "Record an employee's Employment Equity categories (equity:edit). A category outside the Act's is refused; the change is audited by field name only.", "operationId": "putApiEmployeesByIdEquity", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "race": { "type": "string" }, "gender": { "type": "string" }, "disabled": { "type": "boolean" }, "foreignNational": { "type": "boolean" }, "occupationalLevel": { "type": "string" } } }, "example": { "race": "african", "gender": "female", "disabled": false, "foreignNational": false, "occupationalLevel": "skilled" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiEmployeesByIdEquityResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiEmployeesByIdEquityResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/reports/employment-equity": { "get": { "tags": [ "Payroll" ], "summary": "The same report as CSV, table by table, to key into the Department of Employment and Labour's online system.", "operationId": "getApiPayrollReportsEmploymentEquity", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "form", "in": "query", "required": false, "schema": { "type": "string" }, "example": "eea4" }, { "name": "periodEnd", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "csv" } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/shift-register/import": { "post": { "tags": [ "Payroll" ], "summary": "Import a clock's CSV export onto the register: a header row naming the employee (payroll number or ID number), the date, and the hours or In and Out times. One row per person per day — several clockings on a day are added up, a shift past midnight belongs to the day it started. Importing the same file again changes nothing; a corrected file changes only the days it corrects. Employee numbers nobody on the payroll holds, days outside a person's employment and lines that cannot be read are named, never guessed.", "operationId": "postApiPayrollShiftRegisterImport", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string" } } }, "example": { "csv": "Employee Number,Name,Date,In,Out\nG-1,Lindiwe Roster,2026-09-14,06:00,18:00\n" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" }, "unknown": { "type": "array", "items": { "type": "string" } }, "notEmployed": { "type": "array", "items": { "type": "string" } }, "refused": { "type": "array", "items": { "type": "string" } } } }, "example": { "added": 1, "updated": 1, "unchanged": 1, "unknown": [ "text" ], "notEmployed": [ "text" ], "refused": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/inputs/pull/jobs": { "post": { "tags": [ "Payroll" ], "summary": "Pull from Job Cards: every labour line counted in units (bays) whose work date falls in the period, on a completed or invoiced job in the period's company, credited as units of the earning type the line names to the employee its technician is linked to — paid at that person's rate. The work date, not the completion date, which a re-completed job overwrites. Idempotent; a line no longer counted is taken off and counted in `removed`. A line with no earning type, or a technician not on this payroll, is named in `skipped`. Refused with 409 once the run is approved or paid.", "operationId": "postApiPayrollPeriodsByIdInputsPullJobs", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPeriodsByIdInputsPullJobsResponse" }, "example": { "source": "job", "counted": 3, "people": 1, "hours": 3.0, "skipped": [ "text" ], "removed": 0, "inputs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeName": "Overtime", "units": 1.0, "amount": 10005.0, "sourceKind": "standard", "sourceRef": "INV-0001", "note": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/preview": { "post": { "tags": [ "Payroll" ], "summary": "What a run of the period would produce now, saving nothing — the run itself in a transaction that is rolled back, so the figures are the run's own.", "operationId": "postApiPayrollPeriodsByIdPreview", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodId": { "type": "string" }, "locked": { "type": "boolean" }, "payslips": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string" }, "gross": { "type": "number" }, "taxableRemuneration": { "type": "number" }, "paye": { "type": "number" }, "uifEmployee": { "type": "number" }, "uifEmployer": { "type": "number" }, "sdl": { "type": "number" }, "thirdPartyDeductions": { "type": "number" }, "netPay": { "type": "number" }, "etiAmount": { "type": "number" }, "fringeBenefits": { "type": "number" }, "pension": { "type": "number" }, "medical": { "type": "number" } } } } } }, "example": { "periodId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locked": false, "payslips": [ { "employeeId": "8b2d1e44-0c9a-4f71-b6de-5a3c2f1e9d07", "gross": 9500.0, "taxableRemuneration": 9500.0, "paye": 360.0, "uifEmployee": 95.0, "uifEmployer": 95.0, "sdl": 0.0, "thirdPartyDeductions": 95.0, "netPay": 8950.0, "etiAmount": 0.0, "fringeBenefits": 0.0, "pension": 0.0, "medical": 0.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/periods/{periodId}/register": { "get": { "tags": [ "Payroll" ], "summary": "The run's payroll register: a row per payslip, a column per line, the totals (which tie to the payroll journal), and the bank changes since the last approved run. ?format=csv or pdf to download.", "operationId": "getApiPayrollPeriodsByPeriodIdRegister", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "periodId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "csv" } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/periods/{periodId}/variance": { "get": { "tags": [ "Payroll" ], "summary": "Every line that moved since the run before, per employee, with the reason: a new hire, a leaver, a basic salary, a pay input, or the arithmetic.", "operationId": "getApiPayrollPeriodsByPeriodIdVariance", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "periodId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodId": { "type": "string" }, "previousPeriodId": { "type": "string" }, "previousLabel": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "column": { "type": "string" }, "columnLabel": { "type": "string" }, "previous": { "type": "number" }, "current": { "type": "number" }, "change": { "type": "number" }, "reason": { "type": "string" } } } } } }, "example": { "periodId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "previousPeriodId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "previousLabel": "Overtime", "lines": [ { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "column": "text", "columnLabel": "Overtime", "previous": 1.0, "current": 1.0, "change": 1.0, "reason": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/ytd": { "get": { "tags": [ "Payroll" ], "summary": "Year to date by employee from approved and paid runs; taxYear is the year the tax year ends in.", "operationId": "getApiPayrollYtd", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "taxYear", "in": "query", "required": false, "description": "South African year of assessment, named by the year it ENDS in: 2027 is 1 March 2026 to 28 February 2027. A year Ledgr holds no tables for is refused outright rather than served from the nearest one.", "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taxYear": { "type": "integer" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollYtdResponseRowsItem" } }, "totals": { "$ref": "#/components/schemas/GetApiPayrollYtdResponseTotals" } } }, "example": { "taxYear": 2026, "rows": [ { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "employeeName": "Thandi Mokoena", "costCentre": "text", "amounts": { "key": 10005.0 } } ], "totals": { "key": 10005.0 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/periods/{periodId}/cost-to-company": { "get": { "tags": [ "Payroll" ], "summary": "Cost to company for the run, by employee and by cost centre.", "operationId": "getApiPayrollPeriodsByPeriodIdCostToCompany", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "periodId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodId": { "type": "string" }, "byEmployee": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollYtdResponseRowsItem" } }, "byCostCentre": { "$ref": "#/components/schemas/GetApiPayrollYtdResponseTotals" }, "total": { "type": "number" } } }, "example": { "periodId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "byEmployee": [ { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "employeeName": "Thandi Mokoena", "costCentre": "text", "amounts": { "key": 10005.0 } } ], "byCostCentre": { "key": 10005.0 }, "total": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/council-schedules": { "get": { "tags": [ "Payroll" ], "summary": "The bargaining-council schedules Ledgr has published, oldest first: grades by area, allowances and their minimums, levies and the rules, each cited. A pay template follows one by its council, grade and area.", "operationId": "getApiPayrollCouncilSchedules", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "council": { "type": "string" }, "label": { "type": "string" }, "effectiveFrom": { "type": "string", "format": "date" }, "hourlyDivisor": { "type": "number" }, "grades": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "area": { "type": "string" }, "monthlySalary": { "type": "number" } } } }, "allowances": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "minimum": { "type": "number" }, "per": { "type": "string" } } } }, "levies": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "employee": { "type": "number" }, "employer": { "type": "number" } } } }, "rules": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "publishedBy": { "type": "string" }, "publishedAt": { "type": "string" } } } }, "example": [ { "council": "text", "label": "Karoo Fresh Holdings Ltd", "effectiveFrom": "2026-09-01", "hourlyDivisor": 1.0, "grades": [ { "code": "CT-001", "area": "text", "monthlySalary": 1.0 } ], "allowances": [ { "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "minimum": 1.0, "per": "text" } ], "levies": [ { "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "employee": 1.0, "employer": 1.0 } ], "rules": [ "text" ], "source": "referral", "publishedBy": "text", "publishedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/employees/{id}/salary-history": { "get": { "tags": [ "Payroll" ], "summary": "An employee's basic salary as dated figures, oldest first. Empty for a salary that has never been changed with a date.", "operationId": "getApiEmployeesByIdSalaryHistory", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/salary-increases": { "post": { "tags": [ "Payroll" ], "summary": "A bulk increase: a percentage or an amount (exactly one) for the employees named, from a date. Repeating it on the same date lands on the same figure; a date inside an approved run is paid as back pay on the next run.", "operationId": "postApiPayrollSalaryIncreases", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "changed": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "string" } } } }, "example": { "changed": 1, "lines": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/approval": { "get": { "tags": [ "Payroll" ], "summary": "Where the caller stands on approving the run: refused, naming who else may approve it, when they ran or last changed it; asked to confirm the sole approver's statement when nobody else can; otherwise free to approve. warning names, before approval, anyone on the run with PAYE withheld and no income tax reference number (their IRP5 needs one); it never refuses.", "operationId": "getApiPayrollPeriodsByIdApproval", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/approve": { "post": { "tags": [ "Payroll" ], "summary": "Approve the run and lock the payslips. The person who ran or last changed it is refused while somebody else holds payroll approval; a sole approver adds ?confirmSoleApprover=true, and the statement is recorded.", "operationId": "postApiPayrollPeriodsByIdApprove", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPeriodsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPeriodsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/reopen": { "post": { "tags": [ "Payroll" ], "summary": "Reopen an approved period for correction. When the month's EMP201 is noted as filed it answers 409 EMP201_ALREADY_FILED until acknowledgeFiledEmp201=true.", "operationId": "postApiPayrollPeriodsByIdReopen", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "acknowledgeFiledEmp201", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPeriodsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPeriodsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/pay": { "post": { "tags": [ "Payroll" ], "summary": "Record the payment run and post the journal.", "operationId": "postApiPayrollPeriodsByIdPay", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankAccountId": { "type": "string" }, "cashBankAccountId": { "type": "string" } } }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "cashBankAccountId": "9b2e4d61-7a3c-4f85-b0d2-6e1f8a9c3b47" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPeriodsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPeriodsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/emp201": { "get": { "tags": [ "Payroll" ], "summary": "The EMP201 figures for a payroll period (payroll-licensed; the same figures the SARS returns centre shows).", "operationId": "getApiPayrollPeriodsByIdEmp201", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollPeriodsByIdEmp201Response" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollPeriodsByIdEmp201ResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/payslips": { "get": { "tags": [ "Payroll" ], "summary": "Every payslip in a period.", "operationId": "getApiPayrollPeriodsByIdPayslips", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayslipsByIdResponse" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiEmployeesByIdPayslipsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-periods/{id}/journal": { "get": { "tags": [ "Payroll" ], "summary": "The journal the period posts, before or after posting.", "operationId": "getApiPayrollPeriodsByIdJournal", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodId": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "payDate": { "type": "string", "format": "date" }, "periodStatus": { "type": "string" }, "state": { "type": "string" }, "journalId": { "type": "string" }, "journalNumber": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollPeriodsByIdJournalResponseLinesItem" } }, "totalDebit": { "type": "number" }, "totalCredit": { "type": "number" }, "balanced": { "type": "boolean" }, "netPay": { "type": "number" }, "recordedNetPay": { "type": "number" }, "netPayVariance": { "type": "number" }, "employeeCount": { "type": "integer" }, "paymentLines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollPeriodsByIdJournalResponseLinesItem" } }, "paymentJournalId": { "type": "string" }, "paymentJournalNumber": { "type": "string" }, "beneficiaries": { "type": "array", "items": { "type": "object", "properties": { "beneficiaryName": { "type": "string" }, "beneficiaryType": { "type": "string" }, "typeLabel": { "type": "string" }, "employeeAmount": { "type": "number" }, "employerAmount": { "type": "number" }, "total": { "type": "number" } } } } } }, "example": { "periodId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "payDate": "2026-09-01", "periodStatus": "2026-09", "state": "sent", "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "journalNumber": "INV-0001", "lines": [ { "accountCode": "CT-001", "accountName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "debit": 1.0, "credit": 1.0 } ], "totalDebit": 10005.0, "totalCredit": 10005.0, "balanced": true, "netPay": 8700.0, "recordedNetPay": 8700.0, "netPayVariance": 8700.0, "employeeCount": 3, "paymentLines": [ { "accountCode": "CT-001", "accountName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "debit": 1.0, "credit": 1.0 } ], "paymentJournalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "paymentJournalNumber": "INV-0001", "beneficiaries": [ { "beneficiaryName": "Karoo Fresh Holdings Ltd", "beneficiaryType": "standard", "typeLabel": "Standard", "employeeAmount": 10005.0, "employerAmount": 10005.0, "total": 10005.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payslips/{id}": { "get": { "tags": [ "Payroll" ], "summary": "One payslip, line by line.", "operationId": "getApiPayslipsById", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayslipsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayslipsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Payroll" ], "summary": "Adjust a payslip before the period is approved. earningUnits (per-unit types) and earningAmounts (fixed types) add or change a one-off named earning for this employee's period, whether or not the type is on their setup; a re-run keeps it. overtime is held as an amount on Ledgr's Overtime type; commission, bonus and otherAllowances are accepted for older clients and held as amounts on Ledgr's Commission, Bonus and Other allowances types, as earningAmounts would. Pension and medical aid come from the employee's deductions: a figure different from the payslip's is refused with 400.", "operationId": "putApiPayslipsById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "overtime": { "type": "number" }, "commission": { "type": "number" }, "bonus": { "type": "number" }, "travelAllowance": { "type": "number" }, "otherAllowances": { "type": "number" }, "pensionContribution": { "type": "number" }, "medicalAidContribution": { "type": "number" }, "hoursWorked": { "type": "number" }, "overtimeHours": { "type": "number" }, "sundayHours": { "type": "number" }, "publicHolidayHours": { "type": "number" }, "hourlyRate": { "type": "number" }, "overtimeRate": { "type": "number" }, "earningUnits": { "$ref": "#/components/schemas/PutApiPayslipsByIdRequestEarningUnits" }, "earningAmounts": { "$ref": "#/components/schemas/PutApiPayslipsByIdRequestEarningUnits" } } }, "example": { "overtime": 1.0, "commission": 1.0, "bonus": 1.0, "travelAllowance": 1.0, "otherAllowances": 1.0, "pensionContribution": 1.0, "medicalAidContribution": 1.0, "hoursWorked": 3.0, "overtimeHours": 3.0, "sundayHours": 3.0, "publicHolidayHours": 3.0, "hourlyRate": 15.0, "overtimeRate": 15.0, "earningUnits": { "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03": 8.0 }, "earningAmounts": { "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03": 150.0 } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayslipsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayslipsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payslips/{id}/pdf": { "get": { "tags": [ "Payroll" ], "summary": "The payslip as a PDF.", "operationId": "getApiPayslipsByIdPdf", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payslips/{id}/send": { "post": { "tags": [ "Payroll" ], "summary": "Send a payslip by email or WhatsApp.", "operationId": "postApiPayslipsByIdSend", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string" } } }, "example": { "channel": "whatsapp" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayslipsByIdSendResponse" }, "example": { "payslipId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "channel": "email", "delivered": true, "deliveryError": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/irp5": { "get": { "tags": [ "Payroll" ], "summary": "The full IRP5 certificate set for a tax year, per employee, with the validation state e@syFile will apply. period=interim cuts the certificates at 31 August, as the interim EMP501 carries them; the default is annual. payPeriodsWorked is code 3210 as the certificate states it, a part period as its fraction (6.5 for a leaver of 15 September); monthsWorked is the same count rounded to a whole number and is kept only for compatibility.", "operationId": "getApiPayrollIrp5", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "taxYear", "in": "query", "required": false, "description": "South African year of assessment, named by the year it ENDS in: 2027 is 1 March 2026 to 28 February 2027. A year Ledgr holds no tables for is refused outright rather than served from the nearest one.", "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "employeeNumber": { "type": "string" }, "taxNumber": { "type": "string" }, "idNumber": { "type": "string" }, "taxYear": { "type": "string" }, "certificateNumber": { "type": "string" }, "certificateType": { "type": "string" }, "grossRemuneration": { "type": "number" }, "payeDeducted": { "type": "number" }, "uifTotal": { "type": "number" }, "sdl": { "type": "number" }, "pensionTotal": { "type": "number" }, "medicalTotal": { "type": "number" }, "providentTotal": { "type": "number" }, "retirementAnnuityTotal": { "type": "number" }, "medicalTaxCredit": { "type": "number" }, "eti": { "type": "number" }, "totalTaxSdlUif": { "type": "number" }, "employerRetirementBenefit": { "type": "number" }, "employerMedicalBenefit": { "type": "number" }, "monthsWorked": { "type": "integer" }, "payPeriodsWorked": { "type": "number" }, "periodsInYear": { "type": "integer" }, "takeOnIncluded": { "type": "boolean" }, "takeOnGrossRemuneration": { "type": "number" }, "takeOnPaye": { "type": "number" }, "takeOnSourceLabel": { "type": "string" } } } }, "example": [ { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "employeeNumber": "INV-0001", "taxNumber": "9012345678", "idNumber": "INV-0001", "taxYear": "2027", "certificateNumber": "INV-0001", "certificateType": "standard", "grossRemuneration": 1.0, "payeDeducted": 1.0, "uifTotal": 10005.0, "sdl": 1.0, "pensionTotal": 10005.0, "medicalTotal": 10005.0, "providentTotal": 10005.0, "retirementAnnuityTotal": 10005.0, "medicalTaxCredit": 1305.0, "eti": 1.0, "totalTaxSdlUif": 1305.0, "employerRetirementBenefit": 1.0, "employerMedicalBenefit": 1.0, "monthsWorked": 1, "payPeriodsWorked": 1.0, "periodsInYear": 12, "takeOnIncluded": false, "takeOnGrossRemuneration": 1.0, "takeOnPaye": 1.0, "takeOnSourceLabel": "Karoo Fresh Holdings Ltd" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/irp5/replace": { "post": { "tags": [ "Payroll" ], "summary": "Replace one employee's certificate: the standing certificate number is cancelled for good and the next is issued, which every later e@syFile file carries (BRS 3010). Ledgr tells SARS nothing — the cancellation is the employer's to make on e@syFile. 409 when the number given is no longer the standing one.", "operationId": "postApiPayrollIrp5Replace", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employeeId": { "type": "string" }, "certificateNumber": { "type": "string" } } }, "example": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "certificateNumber": "712345678920270200000000E00001" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelled": { "type": "string" }, "issued": { "type": "string" } } }, "example": { "cancelled": "712345678920270200000000E00001", "issued": "7123456789202702000000E00001R2" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/emp501": { "get": { "tags": [ "Payroll" ], "summary": "The EMP501 reconciliation figures for a tax year (payroll-licensed; the same figures the SARS returns centre shows).", "operationId": "getApiPayrollEmp501", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "taxYear", "in": "query", "required": false, "description": "South African year of assessment, named by the year it ENDS in: 2027 is 1 March 2026 to 28 February 2027. A year Ledgr holds no tables for is refused outright rather than served from the nearest one.", "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollEmp501Response" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollEmp501ResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/easyfile": { "get": { "tags": [ "Payroll" ], "summary": "What the e@syFile export would contain, and any records that would fail it. Each certificate's payPeriodsWorked is code 3210 as the certificate states it, a part period as its fraction (7.5484 for a 15 July starter); periodsWorked is the same count rounded to a whole number and is kept only for compatibility.", "operationId": "getApiPayrollEasyfile", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taxYear": { "type": "string" }, "periodFrom": { "type": "string", "format": "date" }, "periodTo": { "type": "string", "format": "date" }, "employerName": { "type": "string" }, "employerPayeNumber": { "type": "string" }, "certificates": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeNumber": { "type": "string" }, "certificateNumber": { "type": "string" }, "certificateType": { "type": "string" }, "employeeName": { "type": "string" }, "taxNumber": { "type": "string" }, "idNumber": { "type": "string" }, "periodsWorked": { "type": "integer" }, "payPeriodsWorked": { "type": "number" }, "grossRemuneration": { "type": "number" }, "paye": { "type": "number" }, "uif": { "type": "number" }, "sdl": { "type": "number" }, "pension": { "type": "number" }, "medical": { "type": "number" }, "medicalTaxCredit": { "type": "number" }, "eti": { "type": "number" }, "totalTaxSdlUif": { "type": "number" }, "validationErrors": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "object" } }, "valid": { "type": "boolean" }, "takeOnIncluded": { "type": "boolean" }, "takeOnGrossRemuneration": { "type": "number" }, "takeOnPaye": { "type": "number" } } } }, "totalGross": { "type": "number" }, "totalPaye": { "type": "number" }, "totalUif": { "type": "number" }, "totalSdl": { "type": "number" }, "totalEti": { "type": "number" }, "excludedPaye": { "type": "number" }, "excludedGross": { "type": "number" }, "validCount": { "type": "integer" }, "invalidCount": { "type": "integer" }, "takeOnCount": { "type": "integer" }, "takeOnPaye": { "type": "number" }, "takeOnGross": { "type": "number" }, "blockingIssues": { "type": "array", "items": { "type": "string" } } } }, "example": { "taxYear": "2027", "periodFrom": "2026-09-01", "periodTo": "2026-09-30", "employerName": "Karoo Fresh Holdings Ltd", "employerPayeNumber": "INV-0001", "certificates": [ { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "certificateNumber": "INV-0001", "certificateType": "standard", "employeeName": "Thandi Mokoena", "taxNumber": "9012345678", "idNumber": "INV-0001", "periodsWorked": 1, "payPeriodsWorked": 1.0, "grossRemuneration": 1.0, "paye": 1.0, "uif": 1.0, "sdl": 1.0, "pension": 1.0, "medical": 1.0, "medicalTaxCredit": 1305.0, "eti": 1.0, "totalTaxSdlUif": 1305.0, "validationErrors": [ "text" ], "warnings": [], "valid": true, "takeOnIncluded": false, "takeOnGrossRemuneration": 1.0, "takeOnPaye": 1.0 } ], "totalGross": 10005.0, "totalPaye": 12400.0, "totalUif": 1062.72, "totalSdl": 890.0, "totalEti": 500.0, "excludedPaye": 1.0, "excludedGross": 1.0, "validCount": 3, "invalidCount": 3, "takeOnCount": 3, "takeOnPaye": 1.0, "takeOnGross": 1.0, "blockingIssues": [ "The control account and the age analysis differ by R0.00." ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/easyfile/import-file": { "get": { "tags": [ "Payroll" ], "summary": "The e@syFile Employer import file itself. period=interim|annual (default annual) chooses the reconciliation; test=true writes an e@syFile TEST import. 422 with the reasons when SARS's BRS would refuse the file.", "operationId": "getApiPayrollEasyfileImportFile", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "taxYear", "in": "query", "required": false, "description": "South African year of assessment, named by the year it ENDS in: 2027 is 1 March 2026 to 28 February 2027. A year Ledgr holds no tables for is refused outright rather than served from the nearest one.", "schema": { "type": "integer" }, "example": "2027" }, { "name": "period", "in": "query", "required": false, "description": "Which of a return's periods this is. Refused rather than defaulted.", "schema": { "type": "string" }, "example": "interim" }, { "name": "test", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "false" } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/easyfile/emp501": { "get": { "tags": [ "Payroll" ], "summary": "The EMP501 schedule that goes with it.", "operationId": "getApiPayrollEasyfileEmp501", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "taxYear", "in": "query", "required": false, "description": "South African year of assessment, named by the year it ENDS in: 2027 is 1 March 2026 to 28 February 2027. A year Ledgr holds no tables for is refused outright rather than served from the nearest one.", "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/periods/{periodId}/remittances": { "get": { "tags": [ "Payroll" ], "summary": "Third-party remittances due for a period — medical aid, provident fund, garnishees.", "operationId": "getApiPayrollPeriodsByPeriodIdRemittances", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "periodId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "beneficiaryId": { "type": "string" }, "beneficiaryName": { "type": "string" }, "beneficiaryType": { "type": "string" }, "typeLabel": { "type": "string" }, "accountReference": { "type": "string" }, "bankName": { "type": "string" }, "bankAccountNumber": { "type": "string" }, "bankBranchCode": { "type": "string" }, "remittanceEmail": { "type": "string" }, "periodLabel": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeNumber": { "type": "string" }, "employeeName": { "type": "string" }, "memberReference": { "type": "string" }, "employeeAmount": { "type": "number" }, "employerAmount": { "type": "number" }, "total": { "type": "number" } } } }, "employeeTotal": { "type": "number" }, "employerTotal": { "type": "number" }, "total": { "type": "number" } } } }, "example": [ { "beneficiaryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "beneficiaryName": "Karoo Fresh Holdings Ltd", "beneficiaryType": "standard", "typeLabel": "Standard", "accountReference": "INV-0001", "bankName": "FNB", "bankAccountNumber": "62012345678", "bankBranchCode": "250655", "remittanceEmail": "accounts@karoofresh.example", "periodLabel": "2026-09", "lines": [ { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "employeeName": "Thandi Mokoena", "memberReference": "INV-0001", "employeeAmount": 10005.0, "employerAmount": 10005.0, "total": 10005.0 } ], "employeeTotal": 10005.0, "employerTotal": 10005.0, "total": 10005.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/beneficiaries": { "get": { "tags": [ "Payroll" ], "summary": "Third-party beneficiaries deductions are paid over to.", "operationId": "getApiPayrollBeneficiaries", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollBeneficiariesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "beneficiaryType": "standard", "typeLabel": "Standard", "accountReference": "INV-0001", "bankName": "FNB", "bankAccountNumber": "62012345678", "bankBranchCode": "250655", "contactEmail": "accounts@karoofresh.example", "contactPhone": "+27 82 555 0143", "remittanceEmail": "accounts@karoofresh.example", "notes": "Budget deferred to the next financial year.", "isActive": true, "memberCount": 3 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Payroll" ], "summary": "Add a beneficiary.", "operationId": "postApiPayrollBeneficiaries", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollBeneficiariesRequest" }, "example": { "name": "Momentum Retirement Annuity", "beneficiaryType": "retirement_fund", "accountReference": "INV-0001", "bankName": "FNB", "bankAccountNumber": "62012345678", "bankBranchCode": "250655", "contactEmail": "accounts@karoofresh.example", "contactPhone": "+27 82 555 0143", "remittanceEmail": "contributions@momentum.example", "notes": "Budget deferred to the next financial year.", "isActive": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollBeneficiariesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollBeneficiariesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/beneficiaries/types": { "get": { "tags": [ "Payroll" ], "summary": "The beneficiary types and how each is treated for PAYE.", "operationId": "getApiPayrollBeneficiariesTypes", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "reducesTax": { "type": "boolean" }, "settles": { "type": "boolean" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "reducesTax": false, "settles": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/beneficiaries/{id}": { "put": { "tags": [ "Payroll" ], "summary": "Update a beneficiary.", "operationId": "putApiPayrollBeneficiariesById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollBeneficiariesRequest" }, "example": { "name": "Momentum Retirement Annuity", "beneficiaryType": "retirement_fund", "accountReference": "INV-0001", "bankName": "FNB", "bankAccountNumber": "62099998888", "bankBranchCode": "250655", "contactEmail": "accounts@karoofresh.example", "contactPhone": "+27 82 555 0143", "remittanceEmail": "accounts@karoofresh.example", "notes": "Budget deferred to the next financial year.", "isActive": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollBeneficiariesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollBeneficiariesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Payroll" ], "summary": "Remove a beneficiary.", "operationId": "deleteApiPayrollBeneficiariesById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/deductions": { "get": { "tags": [ "Payroll" ], "summary": "Employee deductions and their remittance schedules.", "operationId": "getApiPayrollDeductions", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollDeductionsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "beneficiaryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "beneficiaryName": "Karoo Fresh Holdings Ltd", "beneficiaryType": "standard", "memberReference": "INV-0001", "calculation": "fixed", "employeeAmount": 10005.0, "employerAmount": 10005.0, "employeePercent": 15.0, "employerPercent": 15.0, "totalOwing": 10005.0, "totalPaid": 10005.0, "outstanding": 1.0, "orderReference": "INV-0001", "startDate": "2026-09-01", "endDate": "2026-09-30", "isActive": true, "notes": "Budget deferred to the next financial year.", "s34AgreementDocumentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "s34FaultConfirmed": false, "s34ProcedureDate": "2026-09-01", "s34ActualLoss": 1.0, "consentDate": "2026-02-20", "consentReference": "Signed loan agreement, personnel file", "packageNotice": "This run includes a catch-up deduction; the year-to-date total is correct." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Payroll" ], "summary": "Add a deduction against an employee.", "operationId": "postApiPayrollDeductions", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollDeductionsRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollDeductionsRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollDeductionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollDeductionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/deductions/{id}": { "put": { "tags": [ "Payroll" ], "summary": "Change a deduction.", "operationId": "putApiPayrollDeductionsById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollDeductionsRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollDeductionsRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollDeductionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollDeductionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Payroll" ], "summary": "End a deduction.", "operationId": "deleteApiPayrollDeductionsById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/cost-to-company": { "post": { "tags": [ "Payroll" ], "summary": "Structure a package backwards from a cost-to-company figure.", "operationId": "postApiPayrollCostToCompany", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employeeId": { "type": "string" }, "costToCompany": { "type": "number" }, "employerContributions": { "type": "number" }, "uifLiable": { "type": "boolean" }, "sdlExempt": { "type": "boolean" }, "apply": { "type": "boolean" } } }, "example": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costToCompany": 45000.0, "employerContributions": 3200.0, "uifLiable": true, "sdlExempt": false, "apply": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "costToCompany": { "type": "number" }, "basicSalary": { "type": "number" }, "employerContributions": { "type": "number" }, "employerUif": { "type": "number" }, "employerSdl": { "type": "number" }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollCostToCompanyResponseComponentsItem" } } } }, "example": { "costToCompany": 10005.0, "basicSalary": 1.0, "employerContributions": 1.0, "employerUif": 1.0, "employerSdl": 1.0, "components": [ { "label": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/fringe-benefits": { "get": { "tags": [ "Payroll" ], "summary": "Fringe benefits in force.", "operationId": "getApiPayrollFringeBenefits", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollFringeBenefitsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "benefitType": "COMPANY_CAR", "typeLabel": "Company car", "description": "Consulting services — August 2026", "determinedValue": 10005.0, "maintenancePlanIncluded": false, "inputTaxClaimed": false, "employeeBearsMaintenance": false, "depreciationYears": 1, "operatingLeaseCost": 10005.0, "operatingLeaseFuelCost": 10005.0, "businessUseAtLeast80": false, "employeeConsideration": 1.0, "loanBalance": 10005.0, "loanInterestPaid": 1.0, "repoRate": 15.0, "remunerationProxy": 1.0, "abatementNil": false, "atLeastFourRooms": false, "furnished": false, "powerOrFuelSupplied": false, "employerExpenditure": 1.0, "employeeRent": 1.0, "monthlyAmount": 10005.0, "noValueProvision": false, "noValueReason": "Budget deferred to the next financial year.", "startDate": "2026-09-01", "endDate": "2026-09-30", "isActive": true, "notes": "Budget deferred to the next financial year.", "monthlyValue": 10005.0, "monthlyRemuneration": 1.0, "sourceCode": "CT-001", "workings": "text", "issue": "The control account and the age analysis differ by R0.00.", "used": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Payroll" ], "summary": "Add a fringe benefit. ", "operationId": "postApiPayrollFringeBenefits", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollFringeBenefitsRequest" }, "example": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "benefitType": "motor_vehicle", "description": "Consulting services — August 2026", "determinedValue": 420000.0, "maintenancePlanIncluded": true, "inputTaxClaimed": false, "employeeBearsMaintenance": false, "depreciationYears": 1, "operatingLeaseCost": 10005.0, "operatingLeaseFuelCost": 10005.0, "businessUseAtLeast80": false, "employeeConsideration": 1.0, "loanBalance": 10005.0, "loanInterestPaid": 1.0, "repoRate": 15.0, "remunerationProxy": 1.0, "abatementNil": false, "atLeastFourRooms": false, "furnished": false, "powerOrFuelSupplied": false, "employerExpenditure": 1.0, "employeeRent": 1.0, "monthlyAmount": 10005.0, "noValueProvision": false, "noValueReason": "Budget deferred to the next financial year.", "startDate": "2026-09-01", "endDate": "2026-09-30", "isActive": true, "notes": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollFringeBenefitsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollFringeBenefitsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/fringe-benefits/types": { "get": { "tags": [ "Payroll" ], "summary": "The benefit types and the Seventh Schedule rule each follows.", "operationId": "getApiPayrollFringeBenefitsTypes", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "rule": { "type": "string" }, "sourceCode": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "rule": "text", "sourceCode": "CT-001" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/fringe-benefits/{id}": { "put": { "tags": [ "Payroll" ], "summary": "Change a fringe benefit.", "operationId": "putApiPayrollFringeBenefitsById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollFringeBenefitsRequest" }, "example": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "benefitType": "motor_vehicle", "description": "Consulting services — August 2026", "determinedValue": 395000.0, "maintenancePlanIncluded": false, "inputTaxClaimed": false, "employeeBearsMaintenance": false, "depreciationYears": 1, "operatingLeaseCost": 10005.0, "operatingLeaseFuelCost": 10005.0, "businessUseAtLeast80": false, "employeeConsideration": 1.0, "loanBalance": 10005.0, "loanInterestPaid": 1.0, "repoRate": 15.0, "remunerationProxy": 1.0, "abatementNil": false, "atLeastFourRooms": false, "furnished": false, "powerOrFuelSupplied": false, "employerExpenditure": 1.0, "employeeRent": 1.0, "monthlyAmount": 10005.0, "noValueProvision": false, "noValueReason": "Budget deferred to the next financial year.", "startDate": "2026-09-01", "endDate": "2026-09-30", "isActive": true, "notes": "Budget deferred to the next financial year." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollFringeBenefitsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollFringeBenefitsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Payroll" ], "summary": "End a fringe benefit.", "operationId": "deleteApiPayrollFringeBenefitsById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/eti": { "get": { "tags": [ "Payroll" ], "summary": "The Employment Tax Incentive as a view — who qualifies, which of the 24 months they are in, and what may be taken off PAYE.", "operationId": "getApiPayrollEti", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "month", "in": "query", "required": false, "description": "Month of the year, 1-12. Refused rather than defaulted.", "schema": { "type": "string" }, "example": "2026-09" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollEtiResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollEtiResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/eti/employees/{id}": { "put": { "tags": [ "Payroll" ], "summary": "Correct an employee's ETI eligibility or start month.", "operationId": "putApiPayrollEtiEmployeesById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "query", "required": false, "description": "Month of the year, 1-12. Refused rather than defaulted.", "schema": { "type": "string" }, "example": "2026-09" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dateOfBirth": { "type": "string", "format": "date" }, "startDate": { "type": "string", "format": "date" }, "etiMinimumWageMonthly": { "type": "number" }, "clearMinimumWage": { "type": "boolean" }, "etiNoWageRegulatingMeasure": { "type": "boolean" }, "etiMonthsClaimedBeforeLedgr": { "type": "integer" }, "etiExclusion": { "type": "string" }, "etiOrdinaryHoursMonthly": { "type": "number" }, "clearOrdinaryHours": { "type": "boolean" }, "etiSezCode": { "type": "string" } } }, "example": { "dateOfBirth": "1988-04-12", "startDate": "2026-09-01", "etiMinimumWageMonthly": 1.0, "clearMinimumWage": false, "etiNoWageRegulatingMeasure": true, "etiMonthsClaimedBeforeLedgr": 6, "etiExclusion": "Connected person to the employer", "etiOrdinaryHoursMonthly": 3.0, "clearOrdinaryHours": false, "etiSezCode": "COE" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollEtiResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollEtiResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/eti/employer": { "put": { "tags": [ "Payroll" ], "summary": "Record the employer's own ETI facts: whether it is a section 12R qualifying company in a special economic zone, and any ETI Act s3(b) ground that bars it from claiming.", "operationId": "putApiPayrollEtiEmployer", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "month", "in": "query", "required": false, "description": "Month of the year, 1-12. Refused rather than defaulted.", "schema": { "type": "string" }, "example": "2026-09" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sezQualifyingCompany": { "type": "boolean" }, "ineligibleEmployer": { "type": "string" } } }, "example": { "sezQualifyingCompany": true, "ineligibleEmployer": "" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollEtiResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollEtiResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/take-on": { "get": { "tags": [ "Payroll" ], "summary": "Opening year-to-date figures for an employer that switched to Ledgr part-way through a tax year.", "operationId": "getApiPayrollTakeOn", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollTakeOnResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollTakeOnResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/take-on/columns": { "get": { "tags": [ "Payroll" ], "summary": "The columns the take-on import expects.", "operationId": "getApiPayrollTakeOnColumns", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollTakeOnColumnsResponseItem" } }, "example": [ { "header": "text", "meaning": "text" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/take-on/template": { "get": { "tags": [ "Payroll" ], "summary": "A CSV template for the take-on.", "operationId": "getApiPayrollTakeOnTemplate", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/deductions/import/template": { "get": { "tags": [ "Payroll" ], "summary": "The blank recurring-deductions CSV, with a note per column and one worked example row.", "operationId": "getApiPayrollDeductionsImportTemplate", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/deductions/import/columns": { "get": { "tags": [ "Payroll" ], "summary": "Which columns Ledgr can match in a recurring-deductions file, so a caller can build one.", "operationId": "getApiPayrollDeductionsImportColumns", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPayrollTakeOnColumnsResponseItem" } }, "example": [ { "header": "text", "meaning": "text" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/deductions/import": { "post": { "tags": [ "Payroll" ], "summary": "Preview or commit a recurring-deductions CSV. One code path, so the review cannot diverge from what the commit does.", "operationId": "postApiPayrollDeductionsImport", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csvContent": { "type": "string" }, "commit": { "type": "boolean" } } }, "example": { "csvContent": "Employee Number,Deduction,Amount\\nEMP001,Union dues,150.00", "commit": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean" }, "applied": { "type": "integer" }, "skippedExisting": { "type": "integer" }, "beneficiariesCreated": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "rowNumber": { "type": "integer" }, "employeeNumberGiven": { "type": "string" }, "idNumberGiven": { "type": "string" }, "taxNumberGiven": { "type": "string" }, "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "matchedOn": { "type": "string", "format": "date" }, "beneficiaryNameGiven": { "type": "string" }, "beneficiaryId": { "type": "string" }, "beneficiaryIsNew": { "type": "boolean" }, "deductionTypeGiven": { "type": "string" }, "calculationMethodGiven": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object" } }, "willImport": { "type": "boolean" }, "alreadyExists": { "type": "boolean" } } } }, "matchedCount": { "type": "integer" }, "unmatchedCount": { "type": "integer" }, "blockedCount": { "type": "integer" }, "readyCount": { "type": "integer" }, "detectedColumns": { "$ref": "#/components/schemas/GetApiDocumentsInboxResponseCounts" }, "unrecognisedHeaders": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object" } }, "canCommit": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "committed": false, "applied": 1, "skippedExisting": 1, "beneficiariesCreated": 1, "rows": [ { "rowNumber": 1, "employeeNumberGiven": "text", "idNumberGiven": "text", "taxNumberGiven": "text", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "matchedOn": "2026-09-01", "beneficiaryNameGiven": "text", "beneficiaryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "beneficiaryIsNew": false, "deductionTypeGiven": "text", "calculationMethodGiven": "text", "errors": [], "willImport": false, "alreadyExists": false } ], "matchedCount": 3, "unmatchedCount": 3, "blockedCount": 3, "readyCount": 3, "detectedColumns": { "key": 1 }, "unrecognisedHeaders": [ "text" ], "errors": [], "canCommit": false, "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/take-on/import": { "post": { "tags": [ "Payroll" ], "summary": "Import opening YTD figures.", "operationId": "postApiPayrollTakeOnImport", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csvContent": { "type": "string" }, "taxYearEndYear": { "type": "integer" }, "source": { "type": "string" }, "frequency": { "type": "string" }, "note": { "type": "string" }, "commit": { "type": "boolean" }, "acknowledgeExistingRuns": { "type": "boolean" } } }, "example": { "csvContent": "employeeCode,grossYtd,payeYtd\\nE001,240000,52000", "taxYearEndYear": 2027, "source": "OTHER", "frequency": "MONTHLY", "note": "Budget deferred to the next financial year.", "commit": false, "acknowledgeExistingRuns": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean" }, "applied": { "type": "integer" }, "skipped": { "type": "integer" }, "taxYearEndYear": { "type": "integer" }, "taxYear": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "rowNumber": { "type": "integer" }, "employeeNumberGiven": { "type": "string" }, "idNumberGiven": { "type": "string" }, "taxNumberGiven": { "type": "string" }, "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "employeeNumber": { "type": "string" }, "matchedOn": { "type": "string", "format": "date" }, "figures": { "$ref": "#/components/schemas/GetApiPayrollTakeOnResponseEmployeesItemFigures" }, "issues": { "type": "array", "items": { "type": "object" } }, "willImport": { "type": "boolean" }, "replacesExisting": { "type": "boolean" } } } }, "matchedCount": { "type": "integer" }, "unmatchedCount": { "type": "integer" }, "blockedCount": { "type": "integer" }, "warningCount": { "type": "integer" }, "readyCount": { "type": "integer" }, "detectedColumns": { "$ref": "#/components/schemas/GetApiDocumentsInboxResponseCounts" }, "unrecognisedHeaders": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object" } }, "canCommit": { "type": "boolean" }, "existingRunCount": { "type": "integer" }, "existingRunEmployeeCount": { "type": "integer" }, "requiresAcknowledgement": { "type": "boolean" }, "acknowledgementMessage": { "type": "string" }, "message": { "type": "string" } } }, "example": { "committed": false, "applied": 1, "skipped": 1, "taxYearEndYear": 2026, "taxYear": "2027", "rows": [ { "rowNumber": 1, "employeeNumberGiven": "text", "idNumberGiven": "text", "taxNumberGiven": "text", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "employeeNumber": "INV-0001", "matchedOn": "2026-09-01", "figures": { "taxYearEndYear": 2026, "periodsWorked": 1, "remuneration": 1.0, "paye": 1.0, "annualPayments": 1.0, "payeOnAnnualPayments": 1.0, "uifEmployee": 1.0, "uifEmployer": 1.0, "sdl": 1.0, "retirementEmployee": 1.0, "retirementEmployer": 1.0, "medicalEmployee": 1.0, "medicalEmployer": 1.0, "medicalTaxCredit": 1305.0, "fringeBenefits": 1.0, "overtime": 0.0, "commission": 0.0, "travelAllowance": 0.0, "otherAllowances": 0.0, "fringeAccommodation": 0.0, "fringeMedicalCosts": 0.0 }, "issues": [], "willImport": false, "replacesExisting": false } ], "matchedCount": 3, "unmatchedCount": 3, "blockedCount": 3, "warningCount": 3, "readyCount": 3, "detectedColumns": { "key": 1 }, "unrecognisedHeaders": [ "text" ], "errors": [], "canCommit": false, "existingRunCount": 3, "existingRunEmployeeCount": 3, "requiresAcknowledgement": false, "acknowledgementMessage": "Saved.", "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/take-on/{employeeId}": { "put": { "tags": [ "Payroll" ], "summary": "Set one employee's opening figures by hand.", "operationId": "putApiPayrollTakeOnByEmployeeId", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taxYearEndYear": { "type": "integer" }, "periodsWorked": { "type": "integer" }, "frequency": { "type": "string" }, "remuneration": { "type": "number" }, "paye": { "type": "number" }, "annualPayments": { "type": "number" }, "payeOnAnnualPayments": { "type": "number" }, "uifEmployee": { "type": "number" }, "uifEmployer": { "type": "number" }, "sdl": { "type": "number" }, "retirementEmployee": { "type": "number" }, "retirementEmployer": { "type": "number" }, "medicalEmployee": { "type": "number" }, "medicalEmployer": { "type": "number" }, "medicalTaxCredit": { "type": "number" }, "fringeBenefits": { "type": "number" }, "overtime": { "type": "number" }, "commission": { "type": "number" }, "travelAllowance": { "type": "number" }, "otherAllowances": { "type": "number" }, "fringeAccommodation": { "type": "number" }, "fringeMedicalCosts": { "type": "number" }, "source": { "type": "string" }, "note": { "type": "string" }, "acknowledgeExistingRuns": { "type": "boolean" } } }, "example": { "taxYearEndYear": 2026, "periodsWorked": 1, "frequency": "MONTHLY", "remuneration": 240000.0, "paye": 52000.0, "annualPayments": 1.0, "payeOnAnnualPayments": 1.0, "uifEmployee": 1416.96, "uifEmployer": 1.0, "sdl": 1.0, "retirementEmployee": 1.0, "retirementEmployer": 1.0, "medicalEmployee": 1.0, "medicalEmployer": 1.0, "medicalTaxCredit": 1305.0, "fringeBenefits": 1.0, "overtime": 0.0, "commission": 0.0, "travelAllowance": 0.0, "otherAllowances": 0.0, "fringeAccommodation": 0.0, "fringeMedicalCosts": 0.0, "source": "OTHER", "note": "Budget deferred to the next financial year.", "acknowledgeExistingRuns": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollTakeOnResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollTakeOnResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/take-on/{employeeId}/eti-months": { "get": { "tags": [ "Payroll" ], "summary": "The Employment Tax Incentive an employee was claimed for in the months before the payroll moved onto Ledgr, month by month, as the certificate carries them.", "operationId": "getApiPayrollTakeOnByEmployeeIdEtiMonths", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "taxYearEndYear", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "2027" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollTakeOnByEmployeeIdEtiMonthsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollTakeOnByEmployeeIdEtiMonthsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Payroll" ], "summary": "Replace those months for the employee's take-on year (cycle 0 is a month considered and not claimed). Refuses a month Ledgr ran itself, a claim above the Act's monthly maximum, and a year the employee has no take-on figures for.", "operationId": "putApiPayrollTakeOnByEmployeeIdEtiMonths", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taxYearEndYear": { "type": "integer" }, "months": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiPayrollTakeOnByEmployeeIdEtiMonthsRequestMonthsItem" } } } }, "example": { "taxYearEndYear": 2027, "months": [ { "monthNumber": 3, "cycle": 1, "hours": 160.0, "remuneration": 4500.0, "minimumWage": 2500.0, "wagePaid": 4500.0, "etiAmount": 1125.0 } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollTakeOnByEmployeeIdEtiMonthsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollTakeOnByEmployeeIdEtiMonthsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/change-requests": { "get": { "tags": [ "Payroll" ], "summary": "Change requests employees have raised from the self-service portal.", "operationId": "getApiPayrollChangeRequests", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "employeeNumber": { "type": "string" }, "requestType": { "type": "string" }, "typeLabel": { "type": "string" }, "isFinancial": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "current": { "type": "string" }, "requested": { "type": "string" }, "changed": { "type": "boolean" } } } }, "employeeNote": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "reviewedAt": { "type": "string" }, "reviewedByName": { "type": "string" }, "reviewerNote": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "employeeNumber": "INV-0001", "requestType": "standard", "typeLabel": "Standard", "isFinancial": true, "fields": [ { "field": "text", "label": "Karoo Fresh Holdings Ltd", "current": "text", "requested": "text", "changed": true } ], "employeeNote": "Budget deferred to the next financial year.", "status": "sent", "createdAt": "2026-09-01T09:15:00Z", "reviewedAt": "2026-09-01T09:15:00Z", "reviewedByName": "Karoo Fresh Holdings Ltd", "reviewerNote": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/change-requests/{id}/review": { "post": { "tags": [ "Payroll" ], "summary": "Approve or decline an employee's change request.", "operationId": "postApiPayrollChangeRequestsByIdReview", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approve": { "type": "boolean" }, "note": { "type": "string" } } }, "example": { "approve": true, "note": "Bank confirmation letter checked against the account number." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/employees/{id}/portal-link": { "get": { "tags": [ "Payroll" ], "summary": "Whether this employee has a self-service link, and when it was issued.", "operationId": "getApiPayrollEmployeesByIdPortalLink", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollEmployeesByIdPortalLinkResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollEmployeesByIdPortalLinkResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Payroll" ], "summary": "Issue a self-service link. Deliberately RELATIVE — /portal/employee/{token} — so the client composes the host it is already on, which is the better pattern where it applies.", "operationId": "postApiPayrollEmployeesByIdPortalLink", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "url": { "type": "string" }, "expiresInDays": { "type": "integer" }, "replacedPreviousLink": { "type": "boolean" } } }, "example": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "url": "https://app.ledgrsa.com/pay/3f1a7c92", "expiresInDays": 30, "replacedPreviousLink": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Payroll" ], "summary": "Revoke the employee's link.", "operationId": "deleteApiPayrollEmployeesByIdPortalLink", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollEmployeesByIdPortalLinkResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollEmployeesByIdPortalLinkResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/periods/{periodId}/cash-register": { "get": { "tags": [ "Payroll" ], "summary": "The cash pay register for an approved run: every employee paid in cash, what they are handed, and a column for their signature. Those employees are never on the salary payment file.", "operationId": "getApiPayrollPeriodsByPeriodIdCashRegister", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "periodId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/periods/{periodId}/payment-file": { "get": { "tags": [ "Payroll" ], "summary": "The salary payment file for an approved run. format=json is the review — rows with the account number masked, the total, and every employee who cannot be paid with the reason. format=csv is the file itself and answers 422 with the reasons when anything blocks, because a file that silently omits the three employees whose banking details were never captured pays seven of ten people and still foots. bank=bankserv-acb is the Bankserv ACB file that Absa, Nedbank and Capitec import (180-character records, per the layout FNB publishes): it needs the ACB user code and the paying account's branch code saved in PUT /api/payroll-settings under banking, and answers 422 naming the setting when either is missing.", "operationId": "getApiPayrollPeriodsByPeriodIdPaymentFile", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "periodId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" }, { "name": "bank", "in": "query", "required": false, "schema": { "type": "string" }, "example": "fnb" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "payable": { "type": "boolean" }, "payDate": { "type": "string", "format": "date" }, "totalAmount": { "type": "number" }, "paidCount": { "type": "integer" }, "notPaidCount": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "employeeNumber": { "type": "string" }, "beneficiaryName": { "type": "string" }, "bankName": { "type": "string" }, "accountNumberMasked": { "type": "string" }, "branchCode": { "type": "string" }, "amount": { "type": "number" }, "reference": { "type": "string" } } } }, "problems": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "object" } } } }, "example": { "payable": false, "payDate": "2026-09-01", "totalAmount": 10005.0, "paidCount": 3, "notPaidCount": 3, "rows": [ { "employeeNumber": "INV-0001", "beneficiaryName": "Karoo Fresh Holdings Ltd", "bankName": "FNB", "accountNumberMasked": "62012345678", "branchCode": "250655", "amount": 10005.0, "reference": "INV-0001" } ], "problems": [], "warnings": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/returns/uif-declaration": { "get": { "tags": [ "Payroll" ], "summary": "The month's UIF electronic declaration in the Department's own E03 format (U1, code and value), named as the Fund requires (the last eight digits of the UIF reference and the submission number), to e-mail to declarations@uif.gov.za. Every employee is declared, a non-contributor with the reason; the termination codes are E03's. Refused, naming what is missing, without a UIF reference that checks or a contact. test=true marks it TEST, validated by the Fund and not stored.", "operationId": "getApiPayrollReturnsUifDeclaration", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year, as four digits. Refused rather than defaulted when it will not parse.", "schema": { "type": "integer" }, "example": "2026" }, { "name": "month", "in": "query", "required": false, "description": "Month of the year, 1-12. Refused rather than defaulted.", "schema": { "type": "integer" }, "example": "3" }, { "name": "submission", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" }, { "name": "test", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "A plain-text download.", "content": { "text/plain": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/returns/ui19": { "get": { "tags": [ "Payroll" ], "summary": "The UI-19 monthly declaration of employees to the UIF (uFiling). Carries the one thing the EMP201 does not — why each person stopped working here. A leaver with no reason captured, or one whose typed reason does not match a UI-19 reason, BLOCKS the return rather than being guessed at: a benefit claim is assessed against the declared reason, and the wrong one changes what the person may claim.", "operationId": "getApiPayrollReturnsUi19", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "filable": { "type": "boolean" }, "year": { "type": "integer" }, "month": { "type": "integer" }, "employeeCount": { "type": "integer" }, "leaverCount": { "type": "integer" }, "totalRemuneration": { "type": "number" }, "totalUifRemuneration": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "employeeNumber": { "type": "string" }, "employeeName": { "type": "string" }, "identityKind": { "type": "string" }, "identityNumberMasked": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "reasonCode": { "type": "string" }, "reasonLabel": { "type": "string" }, "remuneration": { "type": "number" }, "uifRemuneration": { "type": "number" }, "hoursPerMonth": { "type": "number" } } } }, "issues": { "type": "array", "items": { "type": "object" } } } }, "example": { "filable": false, "year": 2026, "month": 9, "employeeCount": 3, "leaverCount": 3, "totalRemuneration": 10005.0, "totalUifRemuneration": 10005.0, "lines": [ { "employeeNumber": "INV-0001", "employeeName": "Thandi Mokoena", "identityKind": "standard", "identityNumberMasked": "text", "startDate": "2026-09-01", "endDate": "2026-09-30", "reasonCode": "CT-001", "reasonLabel": "Karoo Fresh Holdings Ltd", "remuneration": 1.0, "uifRemuneration": 1.0, "hoursPerMonth": 3.0 } ], "issues": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/returns/roe": { "get": { "tags": [ "Payroll" ], "summary": "The COIDA Return of Earnings (W.As.8) for 1 March to end February. Earnings are capped PER EMPLOYEE, which is the whole arithmetic — capping the payroll total instead overstates the assessment for every employer with anybody above the ceiling. Ledgr does not invent the maximum: a year it has no compiled figure for is refused with instructions, or the employer supplies it as ?maxEarnings=.", "operationId": "getApiPayrollReturnsRoe", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "json" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "filable": { "type": "boolean" }, "assessmentYearEnd": { "type": "integer" }, "periodLabel": { "type": "string" }, "maxEarnings": { "type": "number" }, "employeeCount": { "type": "integer" }, "averageEmployees": { "type": "number" }, "directorCount": { "type": "integer" }, "cappedEmployeeCount": { "type": "integer" }, "totalActualEarnings": { "type": "number" }, "totalAssessableEarnings": { "type": "number" }, "provisionalEstimate": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "employeeNumber": { "type": "string" }, "employeeName": { "type": "string" }, "isDirector": { "type": "boolean" }, "actualEarnings": { "type": "number" }, "assessableEarnings": { "type": "number" }, "cappedBy": { "type": "number" } } } }, "issues": { "type": "array", "items": { "type": "object" } } } }, "example": { "filable": false, "assessmentYearEnd": 1, "periodLabel": "2026-09", "maxEarnings": 1.0, "employeeCount": 3, "averageEmployees": 1.0, "directorCount": 3, "cappedEmployeeCount": 3, "totalActualEarnings": 10005.0, "totalAssessableEarnings": 10005.0, "provisionalEstimate": 1.0, "lines": [ { "employeeNumber": "INV-0001", "employeeName": "Thandi Mokoena", "isDirector": false, "actualEarnings": 1.0, "assessableEarnings": 1.0, "cappedBy": 1.0 } ], "issues": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-settings": { "get": { "tags": [ "Payroll" ], "summary": "The tenant's payslip design and leave entitlements, plus the options the settings screen renders — the section list, the presets, and which sections the BCEA will not let you hide.", "operationId": "getApiPayrollSettings", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollSettingsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollSettingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Payroll" ], "summary": "Update the payslip design, the leave entitlements, or both. A section-wise merge: a section the body does not name keeps its stored value. Refused with the BCEA subsection named if it would hide a required particular or set leave below the statutory minimum.", "operationId": "putApiPayrollSettings", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "design": { "type": "object", "properties": { "title": { "type": "string" }, "accentHex": { "type": "string" }, "showLogo": { "type": "boolean" }, "logoAttachmentId": { "type": "string" }, "logoScalePercent": { "type": "integer" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiPayrollSettingsRequestDesignSectionsItem" } }, "labels": { "type": "object", "properties": { "basic": { "type": "string" } } }, "bankAccount": { "type": "string" }, "density": { "type": "string" }, "showTaxNumber": { "type": "boolean" }, "showIdNumber": { "type": "boolean" }, "message": { "type": "string" }, "footerText": { "type": "string" }, "presetId": { "type": "string" } } }, "leave": { "$ref": "#/components/schemas/PutApiPayrollSettingsRequestLeave" }, "banking": { "$ref": "#/components/schemas/PutApiPayrollSettingsRequestBanking" }, "uif": { "type": "object", "properties": { "departmentReference": { "type": "string" }, "contactPerson": { "type": "string" }, "contactPhone": { "type": "string" }, "contactEmail": { "type": "string" } } } } }, "example": { "design": { "title": "Payslip", "accentHex": "#0D47A1", "showLogo": true, "logoAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "logoScalePercent": 100, "sections": [ { "section": "EMPLOYER", "visible": true } ], "labels": { "basic": "Basic salary" }, "bankAccount": "masked", "density": "compact", "showTaxNumber": true, "showIdNumber": false, "message": "Saved.", "footerText": "Queries: payroll@karoofresh.example", "presetId": "monthly-salaried" }, "leave": { "annualDaysPerCycle": 21.0, "annualAccrualPerMonth": 1.0, "sickDaysPerCycle": 1.0, "familyDaysPerCycle": 1.0, "annualCarryOverDays": 5.0 }, "banking": { "payingBankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "acbUserCode": "AB12", "payingBranchCode": "632005" }, "uif": { "departmentReference": "1916733/3", "contactPerson": "Andy Owner", "contactPhone": "0214441234", "contactEmail": "payroll@acme.example" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollSettingsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollSettingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-settings/preset/{presetId}": { "post": { "tags": [ "Payroll" ], "summary": "Apply a starting point — monthly-salaried, weekly-wage, cost-to-company, shift-and-overtime, small-employer or agriculture. Keeps the tenant's own title, accent, logo and message; replaces the section choices.", "operationId": "postApiPayrollSettingsPresetByPresetId", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "presetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollSettingsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollSettingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll-settings/logo": { "post": { "tags": [ "Payroll" ], "summary": "Upload the mark printed on the payslip. Raw PNG, JPEG or WebP bytes in the body; the attachment id is written into the settings itself, so there is nothing to save afterwards.", "operationId": "postApiPayrollSettingsLogo", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollSettingsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollSettingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/employees/{id}/documents": { "get": { "tags": [ "Payroll" ], "summary": "One employee's document register with every expiry verdict, its own counts, and the kinds that may be filed.", "operationId": "getApiPayrollEmployeesByIdDocuments", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollDocumentExpiriesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollDocumentExpiriesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Payroll" ], "summary": "File a document. Raw bytes in the body with kind, title, issuedOn and expiresOn as query parameters. A row with no file is accepted — recording that a PrDP expires in March, with the card still in the driver's wallet, is the register doing its most useful job.", "operationId": "postApiPayrollEmployeesByIdDocuments", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollDocumentExpiriesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollDocumentExpiriesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/employee-documents/{docId}": { "put": { "tags": [ "Payroll" ], "summary": "Correct the metadata. The file is never replaced — a renewed permit is a new row, so the register keeps what was valid when.", "operationId": "putApiPayrollEmployeeDocumentsByDocId", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "docId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "issuedOn": { "type": "string", "format": "date" }, "expiresOn": { "type": "string", "format": "date" } } }, "example": { "kind": "invoice", "title": "Karoo Fresh Holdings Ltd", "notes": "Budget deferred to the next financial year.", "issuedOn": "2026-09-01", "expiresOn": "2027-03-31" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollDocumentExpiriesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollDocumentExpiriesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Payroll" ], "summary": "Soft delete. The stored file is left alone: a payroll screen is not where somebody should be able to shred the evidence behind an employment.", "operationId": "deleteApiPayrollEmployeeDocumentsByDocId", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "docId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/employee-documents/{docId}/verify": { "post": { "tags": [ "Payroll" ], "summary": "Record that somebody with payroll:edit has looked at it. An employee-uploaded document is not verified by arriving.", "operationId": "postApiPayrollEmployeeDocumentsByDocIdVerify", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "docId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollDocumentExpiriesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollDocumentExpiriesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/earning-types": { "get": { "tags": [ "Payroll" ], "summary": "What this business pays by name — a night-shift allowance, a rations allowance, a tool allowance — with the SARS code each reports under, and the codes and calculations a tenant may pick from.", "operationId": "getApiPayrollEarningTypes", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "types": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollEarningTypesResponse" } }, "codeOptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "guidance": { "type": "string" }, "taxable": { "type": "boolean" }, "postsToLabel": { "type": "string" } } } }, "calculationOptions": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsInspectionChecklistResponseItemsItem" } }, "accountOptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" } } } } } }, "example": { "types": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "sarsCode": "CT-001", "sarsLabel": "Karoo Fresh Holdings Ltd", "calculation": "text", "calculationLabel": "Karoo Fresh Holdings Ltd", "defaultAmount": 10005.0, "defaultPercent": 15.0, "defaultRate": 15.0, "unitLabel": "Karoo Fresh Holdings Ltd", "active": true, "sortOrder": 1, "notes": "Budget deferred to the next financial year.", "taxable": true, "assignedCount": 3, "glAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "postsToLabel": "Karoo Fresh Holdings Ltd", "postsToIsDefault": true, "problem": "text" } ], "codeOptions": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "guidance": "text", "taxable": true, "postsToLabel": "Karoo Fresh Holdings Ltd" } ], "calculationOptions": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd" } ], "accountOptions": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Payroll" ], "summary": "Set up a named earning. The SARS code decides the whole tax treatment: there is deliberately no taxable flag, because a second owner of that fact is how a payslip, an EMP201 and an IRP5 come to disagree about one rand.", "operationId": "postApiPayrollEarningTypes", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollEarningTypesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollEarningTypesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/pay-templates": { "get": { "tags": [ "Payroll" ], "summary": "Pay templates — one per grade or role — with their effective-dated basic, earning and deduction lines and how many employees follow each. An employee's own figures override a template's.", "operationId": "getApiPayrollPayTemplates", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollPayTemplatesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "payBasis": "invoice", "ordinaryHoursWeekly": 3.0, "ordinaryDaysWeekly": 30, "ordinarilyWorksSundays": false, "shiftHours": 3.0, "dayCapHours": 3.0, "fundSalaryWeeklyHours": 3.0, "fundSalaryWeeks": 1.0, "agreements": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "templateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "startsOn": "2026-09-01", "endsOn": "2026-09-01", "averageWeeklyHours": 3.0, "overtimeWeeklyCap": 1.0 } ], "rates": [ { "effectiveFrom": "2026-09-01", "monthlySalary": 1.0, "hourlyRate": 15.0 } ], "earnings": [ { "earningTypeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "earningTypeName": "Overtime", "effectiveFrom": "2026-09-01", "amount": 10005.0, "percent": 15.0, "rate": 15.0, "units": 1.0 } ], "deductions": [ { "beneficiaryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "beneficiaryName": "Highveld Provident Fund", "effectiveFrom": "2026-09-01", "base": "text", "calculation": "text", "employeeAmount": 10005.0, "employerAmount": 10005.0, "employeePercent": 15.0, "employerPercent": 15.0, "unpaidLeave": "follows_base" } ], "employeeCount": 3 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Payroll" ], "summary": "Create a pay template: its name, pay basis (monthly or hourly), working pattern and optional fund salary (weekly hours × weeks a month).", "operationId": "postApiPayrollPayTemplates", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPayTemplatesRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPayTemplatesRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPayTemplatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPayTemplatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/pay-templates/{id}": { "put": { "tags": [ "Payroll" ], "summary": "Rename a pay template or change its pay basis, working pattern or fund salary.", "operationId": "putApiPayrollPayTemplatesById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPayTemplatesRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPayTemplatesRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPayTemplatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPayTemplatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/pay-templates/{id}/rates": { "post": { "tags": [ "Payroll" ], "summary": "The template's basic from a date — a monthly salary or a normal hourly rate. A new date is a new line (a yearly increase); the same date replaces it. Answers whom it reaches and who keeps their own.", "operationId": "postApiPayrollPayTemplatesByIdRates", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "effectiveFrom": { "type": "string", "format": "date" }, "monthlySalary": { "type": "number" }, "hourlyRate": { "type": "null" } } }, "example": { "effectiveFrom": "2026-03-01", "monthlySalary": 7003.0, "hourlyRate": null } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPayTemplatesByIdRatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPayTemplatesByIdRatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/pay-templates/{id}/earnings": { "post": { "tags": [ "Payroll" ], "summary": "A named earning on the template from a date (an allowance, an hours category's rate). Answers whom it reaches and who has their own line for the type.", "operationId": "postApiPayrollPayTemplatesByIdEarnings", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "earningTypeId": { "type": "string" }, "effectiveFrom": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "percent": { "type": "number" }, "rate": { "type": "number" }, "units": { "type": "number" }, "councilAllowance": { "type": "string" } } }, "example": { "earningTypeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "effectiveFrom": "2026-03-01", "amount": 150.0, "percent": 0.0, "rate": 0.0, "units": 0.0, "councilAllowance": "night" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPayTemplatesByIdRatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPayTemplatesByIdRatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/pay-templates/{id}/deductions": { "post": { "tags": [ "Payroll" ], "summary": "A deduction on the template from a date, its base named: basic, money (remuneration in money) or fund_salary; fixed or a percentage, with an employer share. A loan, savings, retirement annuity, union or other line names the collectiveAgreement it rests on (BCEA s34(1)(b)) or is refused. Answers whom it reaches and who has their own.", "operationId": "postApiPayrollPayTemplatesByIdDeductions", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "beneficiaryId": { "type": "string" }, "effectiveFrom": { "type": "string", "format": "date" }, "base": { "type": "string" }, "calculation": { "type": "string" }, "employeeAmount": { "type": "number" }, "employerAmount": { "type": "number" }, "employeePercent": { "type": "number" }, "employerPercent": { "type": "number" }, "unpaidLeave": { "type": "string" }, "collectiveAgreement": { "type": "null" } } }, "example": { "beneficiaryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "effectiveFrom": "2026-03-01", "base": "fund_salary", "calculation": "percent", "employeeAmount": 0.0, "employerAmount": 0.0, "employeePercent": 7.5, "employerPercent": 7.5, "unpaidLeave": "employee_reduced", "collectiveAgreement": null } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollPayTemplatesByIdRatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollPayTemplatesByIdRatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/pay-templates/{id}/assign": { "post": { "tags": [ "Payroll" ], "summary": "Put one or many employees on a template. Their own figures still override it.", "operationId": "postApiPayrollPayTemplatesByIdAssign", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employeeIds": { "type": "array", "items": { "type": "string" } } } }, "example": { "employeeIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "assigned": { "type": "integer" } } }, "example": { "assigned": 6 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/employees/{id}/tax-directives": { "get": { "tags": [ "Payroll" ], "summary": "An employee's tax directives: IRP3(b) a percentage, IRP3(c) an amount, a lump sum, or voluntary additional PAYE. While one is in force the payslip's PAYE follows it.", "operationId": "getApiEmployeesByIdTaxDirectives", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiEmployeesByIdTaxDirectivesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "directiveNumber": "INV-0001", "percent": 15.0, "amount": 10005.0, "validFrom": "2026-09-01", "validTo": "2026-09-30", "taxYearEnd": 1 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Payroll" ], "summary": "Record a tax directive. Refused without its number, figure or start date, or when the tax year it names is not the one it starts in.", "operationId": "postApiEmployeesByIdTaxDirectives", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issuedOn": { "type": "string", "format": "date" }, "kind": { "type": "string" }, "directiveNumber": { "type": "string" }, "percent": { "type": "number" }, "amount": { "type": "null" }, "validFrom": { "type": "string", "format": "date" }, "validTo": { "type": "string", "format": "date" }, "taxYearEnd": { "type": "integer" } } }, "example": { "issuedOn": "2026-08-01", "kind": "irp3b", "directiveNumber": "0123456789", "percent": 18.0, "amount": null, "validFrom": "2026-03-01", "validTo": "2027-02-28", "taxYearEnd": 2027 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiEmployeesByIdTaxDirectivesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "directiveNumber": "INV-0001", "percent": 15.0, "amount": 10005.0, "validFrom": "2026-09-01", "validTo": "2026-09-30", "taxYearEnd": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/employees/{id}/tax-directives/{directiveId}": { "delete": { "tags": [ "Payroll" ], "summary": "Remove a tax directive. PAYE comes from the tables from the next run.", "operationId": "deleteApiEmployeesByIdTaxDirectivesByDirectiveId", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "directiveId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/employees/{id}/averaging-agreements": { "get": { "tags": [ "Payroll" ], "summary": "One employee's own averaging agreements, which replace their template's.", "operationId": "getApiEmployeesByIdAveragingAgreements", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayrollAveragingAgreementsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "templateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "startsOn": "2026-09-01", "endsOn": "2026-09-01", "averageWeeklyHours": 3.0, "overtimeWeeklyCap": 1.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/averaging-agreements": { "post": { "tags": [ "Payroll" ], "summary": "Record an averaging agreement for a template or one employee — a collective agreement (BCEA s12) or a written one (NBCPSS clause 7(2)), at most four months.", "operationId": "postApiPayrollAveragingAgreements", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string" }, "employeeId": { "type": "null" }, "kind": { "type": "string" }, "startsOn": { "type": "string", "format": "date" }, "endsOn": { "type": "string", "format": "date" }, "averageWeeklyHours": { "type": "number" }, "overtimeWeeklyCap": { "type": "number" } } }, "example": { "templateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": null, "kind": "nbcpss_7_2", "startsOn": "2026-10-01", "endsOn": "2027-01-31", "averageWeeklyHours": 48.0, "overtimeWeeklyCap": 12.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollAveragingAgreementsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "templateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "startsOn": "2026-09-01", "endsOn": "2026-09-01", "averageWeeklyHours": 3.0, "overtimeWeeklyCap": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/averaging-agreements/{id}": { "delete": { "tags": [ "Payroll" ], "summary": "Remove an averaging agreement. Hours are settled by the week from the next run.", "operationId": "deleteApiPayrollAveragingAgreementsById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/earning-types/{id}": { "put": { "tags": [ "Payroll" ], "summary": "Change a named earning. Payslips already raised keep what they paid — the name, code and amount are snapshotted onto the payslip.", "operationId": "putApiPayrollEarningTypesById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPayrollEarningTypesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPayrollEarningTypesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Payroll" ], "summary": "Remove a named earning. Refused while any payslip carries it — switch it off instead, or the figure stays on those payslips and on the IRP5 with nothing in settings to explain it.", "operationId": "deleteApiPayrollEarningTypesById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/employees/{employeeId}/earnings": { "get": { "tags": [ "Payroll" ], "summary": "What this employee is on, what each comes to on their current basic pay, and which earnings they are not yet on.", "operationId": "getApiPayrollEmployeesByEmployeeIdEarnings", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollEmployeesByEmployeeIdEarningsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollEmployeesByEmployeeIdEarningsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Payroll" ], "summary": "Put an employee on a named earning, or correct the figure. An upsert: a second post is somebody fixing a number, not asking for a second line.", "operationId": "postApiPayrollEmployeesByEmployeeIdEarnings", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollEmployeesByEmployeeIdEarningsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollEmployeesByEmployeeIdEarningsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/employees/{employeeId}/earnings/{earningTypeId}": { "delete": { "tags": [ "Payroll" ], "summary": "Take an employee off a named earning. Payslips already raised are untouched; the next run simply omits the line.", "operationId": "deleteApiPayrollEmployeesByEmployeeIdEarningsByEarningTypeId", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "earningTypeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollEmployeesByEmployeeIdEarningsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollEmployeesByEmployeeIdEarningsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payslips/bulk-send": { "post": { "tags": [ "Payroll" ], "summary": "Send every final payslip in one pay period, by email or WhatsApp. A draft is skipped and named rather than sent. Always 200 with a per-employee result, so one employee with no address does not fail the rest.", "operationId": "postApiPayslipsBulkSend", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "skipped": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPayslipsByIdSendResponse" } } } }, "example": { "channel": "email", "sent": 1, "failed": 0, "skipped": 1, "results": [ { "payslipId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "channel": "email", "delivered": true, "deliveryError": "text" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/employees/irp5/bulk-send": { "post": { "tags": [ "Payroll" ], "summary": "Send a tax year's IRP5 certificates to the employees, by email (the certificate attached as a PDF) or WhatsApp (a notice that it is ready; refused on a plan that does not include WhatsApp). Only a certificate the employer may deliver is sent: a leaver's, or any employee's once the year has ended and its annual EMP501 is noted as filed. Every other employee is skipped and NAMED with the reason. Always 200 with a per-employee result, so one employee with no address does not fail the rest. taxYear is the year the tax year ends in; omitted, the current one.", "operationId": "postApiEmployeesIrp5BulkSend", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taxYear": { "type": "integer" }, "channel": { "type": "string" } } }, "example": { "taxYear": 2026, "channel": "email" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taxYear": { "type": "string" }, "channel": { "type": "string" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "skipped": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeNumber": { "type": "string" }, "employeeName": { "type": "string" }, "certificateNumber": { "type": "string" }, "channel": { "type": "string" }, "delivered": { "type": "boolean" }, "skipped": { "type": "boolean" }, "deliveryError": { "type": "string" } } } } } }, "example": { "taxYear": "2025/26", "channel": "email", "sent": 1, "failed": 0, "skipped": 1, "results": [ { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "E001", "employeeName": "Thandi Mokoena", "certificateNumber": "7012345676/2026/0001", "channel": "email", "delivered": true, "skipped": false }, { "employeeId": "4a2b8d03-6c75-4e1f-8b22-3d8f9c5a7b14", "employeeNumber": "E002", "employeeName": "Sipho Dlamini", "channel": "email", "delivered": false, "skipped": true, "deliveryError": "Sipho Dlamini: The annual EMP501 for 2025/26 is not noted as filed, and a certificate is not delivered until it is." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/document-expiries": { "get": { "tags": [ "Payroll" ], "summary": "Everything that has lapsed or lapses within 30 days, across every employee, expired first. Optional ?window= widens the horizon to at most a year.", "operationId": "getApiPayrollDocumentExpiries", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "30" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPayrollDocumentExpiriesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPayrollDocumentExpiriesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/payroll/leave-liability": { "get": { "tags": [ "Leave" ], "summary": "What is owed for annual leave earned and not taken, and whether 2160 agrees. asOf (yyyy-mm-dd, today or earlier, default today) states both as at a reporting date: today's days less what later payroll runs granted plus leave dated after it that is already taken, beside 2160 to that day.", "operationId": "getApiPayrollLeaveLiability", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-06-30" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "type": "string" }, "employees": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string" }, "employeeName": { "type": "string" }, "costCentreName": { "type": "string" }, "unusedDays": { "type": "number" }, "dailyRate": { "type": "number" }, "provision": { "type": "number" }, "basis": { "type": "string" }, "employmentEnded": { "type": "boolean" } } } }, "liability": { "type": "number" }, "provisionAccountBalance": { "type": "number" }, "difference": { "type": "number" }, "remeasuredAt": { "type": "string" }, "workingDaysPerYear": { "type": "integer" } } }, "example": { "asOf": "text", "employees": [ { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "costCentreName": "Karoo Fresh Holdings Ltd", "unusedDays": 1.0, "dailyRate": 15.0, "provision": 1.0, "basis": "invoice", "employmentEnded": false } ], "liability": 1.0, "provisionAccountBalance": 10005.0, "difference": 1.0, "remeasuredAt": "2026-09-01T09:15:00Z", "workingDaysPerYear": 260 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/leave-requests": { "get": { "tags": [ "Leave" ], "summary": "Leave requests.", "operationId": "getApiLeaveRequests", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "pending" }, { "name": "employeeId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLeaveRequestsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "leaveType": "annual", "startDate": "2026-09-01", "endDate": "2026-09-30", "daysRequested": 1.0, "reason": "Budget deferred to the next financial year.", "status": "sent", "approvedBy": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Leave" ], "summary": "Raise a leave request.", "operationId": "postApiLeaveRequests", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLeaveRequestsRequest" }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leaveType": "annual", "startDate": "2026-09-14", "endDate": "2026-09-18", "daysRequested": 5.0, "reason": "Family holiday" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLeaveRequestsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLeaveRequestsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/leave-requests/{id}": { "get": { "tags": [ "Leave" ], "summary": "One request.", "operationId": "getApiLeaveRequestsById", "description": "Requires the `payroll:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLeaveRequestsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLeaveRequestsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Leave" ], "summary": "Amend a pending request.", "operationId": "putApiLeaveRequestsById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLeaveRequestsRequest" }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leaveType": "annual", "startDate": "2026-09-14", "endDate": "2026-09-17", "daysRequested": 4.0, "reason": "Budget deferred to the next financial year." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLeaveRequestsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLeaveRequestsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Leave" ], "summary": "Withdraw a request.", "operationId": "deleteApiLeaveRequestsById", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/leave-requests/{id}/approve": { "post": { "tags": [ "Leave" ], "summary": "Approve leave and draw down the balance.", "operationId": "postApiLeaveRequestsByIdApprove", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLeaveRequestsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLeaveRequestsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/leave-requests/{id}/reject": { "post": { "tags": [ "Leave" ], "summary": "Decline leave, with a reason.", "operationId": "postApiLeaveRequestsByIdReject", "description": "Requires the `payroll:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "payroll:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdRejectRequest" }, "example": { "reason": "Two people already off that week" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLeaveRequestsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLeaveRequestsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/products": { "get": { "tags": [ "Inventory" ], "summary": "The catalogue, paged. Search asks the SERVER, on name, SKU and barcode — the barcode arm matters because a typed barcode used to work only while the list was one page.", "operationId": "getApiInventoryProducts", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" }, { "name": "search", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "laptop" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Office%20supplies" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "stockQty": { "type": "integer" }, "stockValue": { "type": "number" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "items": [ { "id": "d616ed4b-6b1d-5b94-88f6-9c115aed7e96", "name": "Developer Kit", "sku": "HW-DEV-K01", "stockQty": 42, "stockValue": 336000.0 } ], "total": 1340, "page": 1, "limit": 50, "totalPages": 27 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Create a product. SKU is unique per tenant, case-insensitively, over live rows; a negative price and a VAT rate outside 0–100 are refused.", "operationId": "postApiInventoryProducts", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vatType": { "type": "string" }, "shelfLifeDays": { "type": "integer" }, "gtin": { "type": "string" }, "isReturnable": { "type": "boolean" }, "returnableDeposit": { "type": "integer" }, "tempMinC": { "type": "integer" }, "tempMaxC": { "type": "integer" }, "preferredSupplierId": { "type": "string" }, "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "costPrice": { "type": "number" }, "sellPrice": { "type": "number" }, "vatRate": { "type": "number" }, "stockQty": { "type": "number" }, "reorderPoint": { "type": "number" }, "unit": { "type": "string" }, "qtyPrecision": { "type": "integer" }, "barcode": { "type": "string" }, "weightKg": { "type": "number" }, "volumeM3": { "type": "number" }, "unitsPerPallet": { "type": "number" }, "costingMethod": { "type": "string" }, "isTracked": { "type": "boolean" }, "tracksSerials": { "type": "boolean" }, "warrantyMonths": { "type": "integer" }, "isSellable": { "type": "boolean" }, "imageIcon": { "type": "string" }, "units": { "$ref": "#/components/schemas/PostApiInventoryProductsRequestUnits" } } }, "example": { "vatType": "standard", "shelfLifeDays": 90, "gtin": "6001234567899", "isReturnable": false, "returnableDeposit": 0, "tempMinC": 2, "tempMaxC": 8, "preferredSupplierId": "7b1e4c2a-9d3f-4e8b-a6c1-5f2d8e9a0b14", "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "category": "general", "costPrice": 10005.0, "sellPrice": 10005.0, "vatRate": 15.0, "stockQty": 3.0, "reorderPoint": 1.0, "unit": "unit", "qtyPrecision": 3, "barcode": "6001234567890", "weightKg": 1.0, "volumeM3": 1.0, "unitsPerPallet": 1.0, "costingMethod": "FIFO", "isTracked": true, "tracksSerials": false, "warrantyMonths": 1, "isSellable": false, "imageIcon": "inventory", "units": { "bag": 25.0 } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryProductsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryProductsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/line-costs": { "get": { "tags": [ "Inventory" ], "summary": "What each product costs on a quote, an order or a deal: a made product at its current standard, else its recipe's roll-up; a bought one at its cost price. Each answer names its basis. Only for roles that may see cost (mrp:view, bom:view or inventory:view). At most 200 products.", "operationId": "getApiInventoryLineCosts", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productIds", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03,8d2e4b17-9c3a-4f60-b5d1-7e0a2c9f4b86" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "unitCost": { "type": "number" }, "basis": { "type": "string" } } } } } }, "example": { "lines": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "unitCost": 2900.0, "basis": "invoice" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/products/{id}": { "get": { "tags": [ "Inventory" ], "summary": "One product, with its stock value for the active company.", "operationId": "getApiInventoryProductsById", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryAdjustResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryAdjustResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Inventory" ], "summary": "Update a product.", "operationId": "putApiInventoryProductsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vatType": { "type": "string" }, "shelfLifeDays": { "type": "integer" }, "gtin": { "type": "string" }, "isReturnable": { "type": "boolean" }, "returnableDeposit": { "type": "integer" }, "tempRange": { "type": "object", "properties": { "minC": { "type": "integer" }, "maxC": { "type": "integer" } } }, "preferredSupplierId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "costPrice": { "type": "number" }, "sellPrice": { "type": "number" }, "vatRate": { "type": "number" }, "stockQty": { "type": "number" }, "reorderPoint": { "type": "number" }, "unit": { "type": "string" }, "qtyPrecision": { "type": "integer" }, "barcode": { "type": "string" }, "weightKg": { "type": "number" }, "volumeM3": { "type": "number" }, "unitsPerPallet": { "type": "number" }, "costingMethod": { "type": "string" }, "isTracked": { "type": "boolean" }, "tracksSerials": { "type": "boolean" }, "warrantyMonths": { "type": "integer" }, "isSellable": { "type": "boolean" }, "imageIcon": { "type": "string" }, "units": { "$ref": "#/components/schemas/PostApiInventoryProductsRequestUnits" } } }, "example": { "vatType": "standard", "shelfLifeDays": 90, "gtin": "6001234567899", "isReturnable": false, "returnableDeposit": 0, "tempRange": { "minC": 2, "maxC": 8 }, "preferredSupplierId": "7b1e4c2a-9d3f-4e8b-a6c1-5f2d8e9a0b14", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "category": "Office supplies", "costPrice": 10005.0, "sellPrice": 10005.0, "vatRate": 15.0, "stockQty": 3.0, "reorderPoint": 1.0, "unit": "each", "qtyPrecision": 3, "barcode": "6001234567890", "weightKg": 1.0, "volumeM3": 1.0, "unitsPerPallet": 1.0, "costingMethod": "eft", "isTracked": true, "tracksSerials": true, "warrantyMonths": 1, "isSellable": true, "imageIcon": "inventory", "units": { "bag": 25.0 } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryProductsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryProductsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Inventory" ], "summary": "Soft-delete a product. REFUSED while there is stock to lose — a write-off has to be an adjustment somebody posts, not a silent disappearance with the value still sitting in 1310.", "operationId": "deleteApiInventoryProductsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/products/lookup": { "get": { "tags": [ "Inventory" ], "summary": "Resolve one product by barcode or SKU, for the scanner and the line picker. Takes the oldest match rather than nothing, for tenants whose data predates the uniqueness guard.", "operationId": "getApiInventoryProductsLookup", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sku", "in": "query", "required": false, "schema": { "type": "string" }, "example": "HW-DEV-K01" }, { "name": "barcode", "in": "query", "required": false, "schema": { "type": "string" }, "example": "6001234567890" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryAdjustResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryAdjustResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/products/low-stock": { "get": { "tags": [ "Inventory" ], "summary": "Everything below its reorder point, tenant-wide — counting the loaded page would report page one's shortages as the whole catalogue.", "operationId": "getApiInventoryProductsLowStock", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryAdjustResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "category": "Office supplies", "costPrice": 10005.0, "sellPrice": 10005.0, "vatRate": 15.0, "stockQty": 3.0, "reorderPoint": 1.0, "unit": "each", "qtyPrecision": 3, "barcode": "6001234567890", "costingMethod": "eft", "isTracked": true, "stockValue": 10005.0, "tracksSerials": false, "warrantyMonths": 1, "imageIcon": "text", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/products/summary": { "get": { "tags": [ "Inventory" ], "summary": "The catalogue's totals for the active company, over every live product rather than a page: how many products, how many are tracked or services, and the stock and sell value, composed row by row as the list composes them.", "operationId": "getApiInventoryProductsSummary", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalProducts": { "type": "integer" }, "trackedProducts": { "type": "integer" }, "serviceProducts": { "type": "integer" }, "stockValue": { "type": "number" }, "sellValue": { "type": "number" } } }, "example": { "totalProducts": 156, "trackedProducts": 151, "serviceProducts": 5, "stockValue": 10005.0, "sellValue": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/products/low-stock-by-location": { "get": { "tags": [ "Inventory" ], "summary": "The same, split by location.", "operationId": "getApiInventoryProductsLowStockByLocation", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "qty": { "type": "number" }, "reorderPoint": { "type": "number" }, "reorderQty": { "type": "number" }, "isLocationOverride": { "type": "boolean" } } } }, "example": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "qty": 3.0, "reorderPoint": 1.0, "reorderQty": 3.0, "isLocationOverride": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/purchase-suggestions": { "get": { "tags": [ "Inventory" ], "summary": "What the low-stock list should buy, grouped by supplier: the reorder quantity where one is set, otherwise up to the reorder point, after what is already on order, rounded up to the product's counting precision. Without locationId, the active company's list; with it, that location's own thresholds. Products with no supplier (product, approved vendor list, then last purchase order) are listed apart; covered ones are named. Read-only — each draft is raised through POST /api/invoices with documentType \"po\".", "operationId": "getApiInventoryPurchaseSuggestions", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "4d8e2a61-7c3b-4f90-b5e2-8a1c6d9f3e27" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "null" }, "locationName": { "type": "null" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "qtyPrecision": { "type": "integer" }, "onHand": { "type": "number" }, "onOrder": { "type": "number" }, "reorderPoint": { "type": "number" }, "reorderQty": { "type": "null" }, "suggestedQty": { "type": "number" }, "unitCost": { "type": "number" }, "vatRate": { "type": "number" }, "supplierId": { "type": "string" }, "supplierSource": { "type": "string" } } } } } } }, "unassigned": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "qtyPrecision": { "type": "integer" }, "onHand": { "type": "number" }, "onOrder": { "type": "number" }, "reorderPoint": { "type": "number" }, "reorderQty": { "type": "null" }, "suggestedQty": { "type": "number" }, "unitCost": { "type": "number" }, "vatRate": { "type": "number" }, "supplierId": { "type": "null" }, "supplierSource": { "type": "null" } } } }, "covered": { "type": "array", "items": { "type": "object" } }, "suppliers": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } } } }, "example": { "locationId": null, "locationName": null, "groups": [ { "supplierId": "7b1e4c2a-9d3f-4e8b-a6c1-5f2d8e9a0b14", "supplierName": "Sasko Bakeries", "lines": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "BRD-700", "name": "Brown bread 700g", "unit": "unit", "qtyPrecision": 0, "onHand": 3.0, "onOrder": 0.0, "reorderPoint": 10.0, "reorderQty": null, "suggestedQty": 7.0, "unitCost": 12.0, "vatRate": 15.0, "supplierId": "7b1e4c2a-9d3f-4e8b-a6c1-5f2d8e9a0b14", "supplierSource": "product" } ] } ], "unassigned": [ { "productId": "9c2d7e41-0a5b-4f3c-8e6d-1b7a2c9f4e58", "sku": "SLT-1", "name": "Table salt 1kg", "unit": "unit", "qtyPrecision": 0, "onHand": 3.0, "onOrder": 0.0, "reorderPoint": 10.0, "reorderQty": null, "suggestedQty": 5.0, "unitCost": 12.0, "vatRate": 15.0, "supplierId": null, "supplierSource": null } ], "covered": [], "suppliers": [ { "id": "7b1e4c2a-9d3f-4e8b-a6c1-5f2d8e9a0b14", "name": "Sasko Bakeries" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/suppliers": { "get": { "tags": [ "Inventory" ], "summary": "Active suppliers, two fields each, for the product form's preferred-supplier picker — readable with inventory:view alone.", "operationId": "getApiInventorySuppliers", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "example": [ { "id": "7b1e4c2a-9d3f-4e8b-a6c1-5f2d8e9a0b14", "name": "Sasko Bakeries" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/labels": { "post": { "tags": [ "Inventory" ], "summary": "A PDF sheet of product labels: name, SKU, shelf price and a barcode — EAN-13 when the product's barcode is a valid EAN-13, otherwise Code 128 of the barcode or the SKU. layout is a4-3x8 (24 to an A4 sheet) or roll-50x30 (one 50 x 30 mm label a page). Generated on each request, never stored.", "operationId": "postApiInventoryLabels", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "copies": { "type": "integer" } } } }, "layout": { "type": "string" } } }, "example": { "items": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "copies": 3 } ], "layout": "a4-3x8" } } } }, "responses": { "201": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/products/{id}/images": { "get": { "tags": [ "Inventory" ], "summary": "Product photographs.", "operationId": "getApiInventoryProductsByIdImages", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryProductsByIdImagesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "url": "https://app.ledgrsa.com/pay/3f1a7c92" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Upload a photograph as a multipart file part, at most 5 MB; the server recompresses and stores the object, never base64 in Postgres. Send ?clientId= (the id the device minted for the photograph when it was staged): the first upload answers 201, a retry 200 with the photograph already stored, and an id already used by another business is refused. An unknown or deleted product answers 404.", "operationId": "postApiInventoryProductsByIdImages", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryProductsByIdImagesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "url": "https://app.ledgrsa.com/pay/3f1a7c92" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/products/{id}/images/{imageId}": { "delete": { "tags": [ "Inventory" ], "summary": "Remove a photograph.", "operationId": "deleteApiInventoryProductsByIdImagesByImageId", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "imageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/categories": { "get": { "tags": [ "Inventory" ], "summary": "Product categories.", "operationId": "getApiInventoryCategories", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryCategoriesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "color": "#0D47A1", "icon": "text", "description": "Consulting services — August 2026", "sortOrder": 1, "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Add a category.", "operationId": "postApiInventoryCategories", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer" }, "accountCode": { "type": "string" } } }, "example": { "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "color": "#0D47A1", "icon": "box", "description": "Consulting services — August 2026", "sortOrder": 1, "accountCode": "6190" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryCategoriesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryCategoriesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/categories/{id}": { "put": { "tags": [ "Inventory" ], "summary": "Rename a category.", "operationId": "putApiInventoryCategoriesById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiExpensesCategoriesByIdRequest" }, "example": { "code": "CT-001", "name": "Workshop consumables", "color": "#0D47A1", "icon": "box", "description": "Consulting services — August 2026", "sortOrder": 1, "isActive": true, "accountCode": "6190" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryCategoriesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryCategoriesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Inventory" ], "summary": "Remove a category.", "operationId": "deleteApiInventoryCategoriesById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/price-lists": { "get": { "tags": [ "Inventory" ], "summary": "Price lists visible in the active company, with how many prices and customers each carries. A price excludes VAT, like a product's sell price.", "operationId": "getApiInventoryPriceLists", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryPriceListsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "priceCount": 3, "customerCount": 3, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Make a price list in the active company. Two live lists of the same name in one company are refused.", "operationId": "postApiInventoryPriceLists", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryPriceListsRequest" }, "example": { "name": "Trade" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryPriceListsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryPriceListsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/price-lists/{id}": { "put": { "tags": [ "Inventory" ], "summary": "Rename a price list.", "operationId": "putApiInventoryPriceListsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryPriceListsRequest" }, "example": { "name": "Trade customers" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryPriceListsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryPriceListsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Inventory" ], "summary": "Delete a price list. Its customers go back to each product's own price, and the answer says how many did.", "operationId": "deleteApiInventoryPriceListsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "customersDetached": { "type": "integer" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "customersDetached": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/price-lists/{id}/products": { "get": { "tags": [ "Inventory" ], "summary": "A list's price sheet: products (searched on name, SKU and barcode, paged) with their variants, each with its own sell price and the list's price.", "operationId": "getApiInventoryPriceListsByIdProducts", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "drill" }, { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiInventoryPriceListsByIdPricesResponse" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "items": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "unit": "each", "sellPrice": 10005.0, "listPrice": 10005.0, "variants": [ { "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "sellPrice": 10005.0, "listPrice": 10005.0 } ] } ], "total": 42, "page": 1, "limit": 50, "totalPages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/price-lists/{id}/prices": { "put": { "tags": [ "Inventory" ], "summary": "Set one price on a list, for a product or one of its variants. No unitPrice clears it. Excludes VAT; stored at two decimals.", "operationId": "putApiInventoryPriceListsByIdPrices", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "minQty": { "type": "number" }, "productId": { "type": "string" }, "variantId": { "type": "null" }, "unitPrice": { "type": "number" } } }, "example": { "minQty": 1.0, "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": null, "unitPrice": 850.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiInventoryPriceListsByIdPricesResponse" }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "unit": "each", "sellPrice": 10005.0, "listPrice": 10005.0, "variants": [ { "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "sellPrice": 10005.0, "listPrice": 10005.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/variants": { "get": { "tags": [ "Inventory" ], "summary": "Product variants — size, colour, configuration — each with its on-hand counted from the batches tagged to it.", "operationId": "getApiInventoryVariants", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryVariantsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "attributes": "text", "costPrice": 10005.0, "sellPrice": 10005.0, "stockQty": 3.0, "barcode": "6001234567890", "isActive": true, "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Add a variant, optionally with opening stock opened as a batch (a typed stock figure is refused).", "operationId": "postApiInventoryVariants", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "attributes": { "type": "string" }, "costPrice": { "type": "number" }, "sellPrice": { "type": "number" }, "stockQty": { "type": "null" }, "openingQty": { "type": "number" }, "openingUnitCost": { "type": "number" }, "barcode": { "type": "string" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "HW-DEV-K01-16-512", "name": "16GB / 512GB", "attributes": "{\"colour\":\"black\"}", "costPrice": 10005.0, "sellPrice": 14500.0, "stockQty": null, "openingQty": 3.0, "openingUnitCost": 10005.0, "barcode": "6001234567890" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryVariantsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryVariantsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/variants/{id}": { "put": { "tags": [ "Inventory" ], "summary": "Update a variant.", "operationId": "putApiInventoryVariantsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string" }, "name": { "type": "string" }, "attributes": { "type": "string" }, "costPrice": { "type": "number" }, "sellPrice": { "type": "number" }, "stockQty": { "type": "null" }, "barcode": { "type": "string" }, "isActive": { "type": "boolean" } } }, "example": { "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "attributes": "{\"colour\":\"black\"}", "costPrice": 10005.0, "sellPrice": 14900.0, "stockQty": null, "barcode": "6001234567890", "isActive": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryVariantsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryVariantsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Inventory" ], "summary": "Remove a variant.", "operationId": "deleteApiInventoryVariantsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/reports/valuation": { "get": { "tags": [ "Inventory" ], "summary": "Stock value as at a date, per product, beside the Inventory account (1310) on that date and the difference. Today is read from the open batches; an earlier date is rebuilt from the stock movements and says so.", "operationId": "getApiInventoryReportsValuation", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "type": "string", "format": "date" }, "basis": { "type": "string" }, "exact": { "type": "boolean" }, "note": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "qty": { "type": "number" }, "value": { "type": "number" }, "locations": { "type": "array", "items": { "type": "object" } } } } }, "locations": { "type": "array", "items": { "type": "object" } }, "totalValue": { "type": "number" }, "ledgerBalance": { "type": "number" }, "difference": { "type": "number" }, "movementsReversed": { "type": "integer" }, "movementsWithoutCost": { "type": "integer" } } }, "example": { "asOf": "2026-09-01", "basis": "movements", "exact": false, "note": "Rebuilt from today's batches by reversing 12 stock movements dated after 2026-09-01, each at the cost it moved at.", "rows": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Lenovo ThinkPad 14", "unit": "each", "qty": 3.0, "value": 30015.0, "locations": [] } ], "locations": [], "totalValue": 30015.0, "ledgerBalance": 30015.0, "difference": 0.0, "movementsReversed": 12, "movementsWithoutCost": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/reports/aging": { "get": { "tags": [ "Inventory" ], "summary": "Open batch quantity and value by age — 0–30, 31–90, 91–180 and over 180 days from each batch's received date — per product, totalling the stock value.", "operationId": "getApiInventoryReportsAging", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "type": "string", "format": "date" }, "bands": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" } } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "qty": { "type": "array", "items": { "type": "number" } }, "value": { "type": "array", "items": { "type": "number" } }, "totalQty": { "type": "number" }, "totalValue": { "type": "number" } } } }, "totalValue": { "type": "number" } } }, "example": { "asOf": "2026-09-01", "bands": [ { "key": "0-30", "label": "0–30 days", "value": 30015.0 }, { "key": "31-90", "label": "31–90 days", "value": 0.0 }, { "key": "91-180", "label": "91–180 days", "value": 0.0 }, { "key": "180+", "label": "Over 180 days", "value": 0.0 } ], "rows": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Lenovo ThinkPad 14", "unit": "each", "qty": [ 3.0, 0.0, 0.0, 0.0 ], "value": [ 30015.0, 0.0, 0.0, 0.0 ], "totalQty": 3.0, "totalValue": 30015.0 } ], "totalValue": 30015.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/locations": { "get": { "tags": [ "Inventory" ], "summary": "Stock locations.", "operationId": "getApiInventoryLocations", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryLocationsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "address": "12 Long Street, Cape Town, 8001", "type": "standard", "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Add a location.", "operationId": "postApiInventoryLocations", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "type": { "type": "string" }, "suburb": { "type": "string" }, "city": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Durban Showroom", "address": "12 Long Street, Cape Town, 8001", "type": "standard", "suburb": "Umhlanga", "city": "Durban" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryLocationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryLocationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/locations/{id}": { "put": { "tags": [ "Inventory" ], "summary": "Rename a location.", "operationId": "putApiInventoryLocationsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "type": { "type": "string" }, "isActive": { "type": "boolean" }, "suburb": { "type": "string" }, "city": { "type": "string" } } }, "example": { "name": "Durban Showroom (Umhlanga)", "address": "12 Long Street, Cape Town, 8001", "type": "standard", "isActive": true, "suburb": "Umhlanga", "city": "Durban" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryLocationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryLocationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Inventory" ], "summary": "Remove a location. REFUSED while it holds stock — its stock_levels rows would otherwise point at a warehouse no list shows, while still counting towards the product's total.", "operationId": "deleteApiInventoryLocationsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/locations/{id}/sell-from": { "put": { "tags": [ "Inventory" ], "summary": "Make this the location the company's sales ship from (\"Sell from here\"). Invoices, credit notes, reservations, deliveries and job-card parts take and return stock here. Until a company chooses, sales ship from the first location holding stock. Answers the company's locations, with sellsFrom on the one sales now use.", "operationId": "putApiInventoryLocationsByIdSellFrom", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInvoicesRequestCustomFields" }, "example": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "type": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "sellFromChosen": { "type": "boolean" }, "sellsFrom": { "type": "boolean" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Durban Showroom", "address": "12 Long Street, Cape Town, 8001", "type": "standard", "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "sellFromChosen": true, "sellsFrom": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/stock-levels": { "get": { "tags": [ "Inventory" ], "summary": "On-hand by product and location.", "operationId": "getApiInventoryStockLevels", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "productId": { "type": "string" }, "locationId": { "type": "string" }, "qty": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qty": 3.0, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/products/{id}/pool-stock": { "get": { "tags": [ "Inventory" ], "summary": "A product's stock at the other companies this one shares inventory with.", "operationId": "getApiInventoryProductsByIdPoolStock", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "companyId": { "type": "string" }, "companyName": { "type": "string" }, "locationName": { "type": "string" }, "qty": { "type": "number" } } } }, "example": [ { "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyName": "Highveld Trading Co (Pty) Ltd", "locationName": "Main warehouse", "qty": 3.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/movements": { "get": { "tags": [ "Inventory" ], "summary": "Stock movement history with a running balance.", "operationId": "getApiInventoryMovements", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "productId": { "type": "string" }, "locationId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "type": { "type": "string" }, "qty": { "type": "number" }, "reference": { "type": "string" }, "balance": { "type": "number" }, "createdAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "type": "standard", "qty": 3.0, "reference": "INV-0001", "balance": 10005.0, "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/adjust": { "post": { "tags": [ "Inventory" ], "summary": "Adjust stock up or down and post the journal. A negative resulting level is refused.", "operationId": "postApiInventoryAdjust", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "deltaQty": { "type": "number" }, "reason": { "type": "string" }, "reasonCode": { "type": "string" }, "locationId": { "type": "string" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "deltaQty": 2.0, "reason": "Captured during the August review", "reasonCode": "count", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryAdjustResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryAdjustResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/write-down-to-nrv": { "post": { "tags": [ "Inventory" ], "summary": "Carry a product's stock at the lower of cost and net realisable value: lowers the open batches to the NRV and posts the write-down, or raises batches written down earlier, never above cost.", "operationId": "postApiInventoryWriteDownToNrv", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "nrvPerUnit": { "type": "number" }, "reason": { "type": "string" }, "date": { "type": "string", "format": "date" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "nrvPerUnit": 8700.0, "reason": "Plate price fell; NRV quoted by two mills", "date": "2026-02-28" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "nrvPerUnit": { "type": "number" }, "writtenDown": { "type": "number" }, "reversed": { "type": "number" }, "layers": { "type": "integer" }, "stockValue": { "type": "number" }, "journalId": { "type": "string" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "nrvPerUnit": 8700.0, "writtenDown": 74400.0, "reversed": 0.0, "layers": 1, "stockValue": 208800.0, "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/reorder-points": { "get": { "tags": [ "Inventory" ], "summary": "Reorder points and reorder quantities.", "operationId": "getApiInventoryReorderPoints", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiInventoryReorderPointsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reorderPoint": 1.0, "reorderQty": 3.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Inventory" ], "summary": "Set a reorder point.", "operationId": "putApiInventoryReorderPoints", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "locationId": { "type": "string" }, "reorderPoint": { "type": "number" }, "reorderQty": { "type": "number" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reorderPoint": 20.0, "reorderQty": 100.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiInventoryReorderPointsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reorderPoint": 1.0, "reorderQty": 3.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/transfers": { "get": { "tags": [ "Inventory" ], "summary": "Inter-location transfers.", "operationId": "getApiInventoryTransfers", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryTransferResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qty": 3.0, "reference": "INV-0001", "status": "sent", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/transfer": { "post": { "tags": [ "Inventory" ], "summary": "Raise a transfer. A shortfall is refused rather than driving the source negative, and the batch layers travel with the goods.", "operationId": "postApiInventoryTransfer", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "fromLocationId": { "type": "string" }, "toLocationId": { "type": "string" }, "qty": { "type": "number" }, "reference": { "type": "string" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qty": 2.0, "reference": "INV-0001" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryTransferResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qty": 3.0, "reference": "INV-0001", "status": "sent", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/transfers/{id}/confirm": { "post": { "tags": [ "Inventory" ], "summary": "Receive a transfer. StockCostingEngine.relocate moves the batch layers HERE — on receipt, not on despatch, because the sum of batch values has to keep equalling 1310 at every instant.", "operationId": "postApiInventoryTransfersByIdConfirm", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventorySerialsByIdScrapRequest" }, "example": { "notes": "Received in full, no damage" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryTransfersByIdCancelResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "received", "qty": 3.0, "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "TRF-0001", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T11:40:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/transfers/{id}/cancel": { "post": { "tags": [ "Inventory" ], "summary": "Cancel a transfer in flight.", "operationId": "postApiInventoryTransfersByIdCancel", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryTransfersByIdCancelResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "cancelled", "qty": 3.0, "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "TRF-0001", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T11:40:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/grni": { "get": { "tags": [ "Inventory" ], "summary": "Goods received by hand and not yet invoiced, oldest first — the aged list behind 2115 Goods Received Not Invoiced for receipts with no order. A bill line, expense or bank line that names the product clears a receipt.", "operationId": "getApiInventoryGrni", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-31" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "type": "string", "format": "date" }, "receipts": { "type": "array", "items": { "type": "object", "properties": { "receiptId": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "supplier": { "type": "string" }, "receivedOn": { "type": "string", "format": "date" }, "daysOpen": { "type": "integer" }, "qtyOpen": { "type": "number" }, "unitCost": { "type": "number" }, "value": { "type": "number" } } } }, "total": { "type": "number" } } }, "example": { "asOf": "2026-10-31", "receipts": [ { "receiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Steel bar", "supplier": "Karoo Fresh Holdings Ltd", "receivedOn": "2026-10-12", "daysOpen": 19, "qtyOpen": 10.0, "unitCost": 100.0, "value": 1000.0 } ], "total": 1000.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/batches": { "get": { "tags": [ "Inventory" ], "summary": "Batch layers — quantity remaining, unit cost, supplier, received and expiry dates, and the location they are actually at.", "operationId": "getApiInventoryBatches", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryBatchesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "batchNumber": "INV-0001", "supplier": "Karoo Fresh Holdings Ltd", "receivedDate": "2026-09-01", "expiryDate": "2026-09-01", "qtyReceived": 1.0, "qtyRemaining": 1.0, "unitCost": 2900.0, "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Create a batch layer — receive stock by hand. kind says what the units are: purchase (the default; owed to the supplier until a bill, expense or bank line names the product — DR 1310 / CR 2115), found (stock found on a count — CR 5070) or opening (stock already owned when the books opened — CR 3500).", "operationId": "postApiInventoryBatches", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "type": "string" }, "locationId": { "type": "string" }, "batchNumber": { "type": "string" }, "supplier": { "type": "string" }, "receivedDate": { "type": "string", "format": "date" }, "expiryDate": { "type": "string", "format": "date" }, "qtyReceived": { "type": "number" }, "unitCost": { "type": "number" }, "notes": { "type": "string" }, "serialNumbers": { "type": "array", "items": { "type": "string" } }, "kind": { "type": "string" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "batchNumber": "INV-0001", "supplier": "Karoo Fresh Holdings Ltd", "receivedDate": "2026-09-30", "expiryDate": "2027-08-20", "qtyReceived": 2.0, "unitCost": 1500.0, "notes": "Budget deferred to the next financial year.", "serialNumbers": [ "INV-0001" ], "kind": "purchase" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryBatchesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "batchNumber": "INV-0001", "supplier": "Karoo Fresh Holdings Ltd", "receivedDate": "2026-09-01", "expiryDate": "2026-09-01", "qtyReceived": 1.0, "qtyRemaining": 1.0, "unitCost": 2900.0, "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/batches/expiring": { "get": { "tags": [ "Inventory" ], "summary": "Batches expiring inside a window, with the location that holds them — naming the wrong branch is worse than naming none.", "operationId": "getApiInventoryBatchesExpiring", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "How many days forward or back the window covers.", "schema": { "type": "integer" }, "example": "30" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "batchNumber": { "type": "string" }, "expiryDate": { "type": "string", "format": "date" }, "daysUntilExpiry": { "type": "integer" }, "qtyRemaining": { "type": "number" }, "locationName": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "batchNumber": "INV-0001", "expiryDate": "2026-09-01", "daysUntilExpiry": 30, "qtyRemaining": 1.0, "locationName": "Karoo Fresh Holdings Ltd" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/batches/{id}": { "delete": { "tags": [ "Inventory" ], "summary": "Remove an empty batch layer.", "operationId": "deleteApiInventoryBatchesById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/batches/{id}/recall": { "get": { "tags": [ "Inventory" ], "summary": "Recall a lot: every customer it went to, with the document and quantity, and what is still on hand. On the Inventory licence.", "operationId": "getApiInventoryBatchesByIdRecall", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInventoryBatchesByIdRecallResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInventoryBatchesByIdRecallResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/batches/{id}/quarantine": { "post": { "tags": [ "Inventory" ], "summary": "Quarantine what is left of a lot: it stays valued but nothing may sell, issue or build from it. Answers the recall.", "operationId": "postApiInventoryBatchesByIdQuarantine", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInventoryBatchesByIdRecallResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInventoryBatchesByIdRecallResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/serials": { "get": { "tags": [ "Inventory" ], "summary": "Serialised units and their status.", "operationId": "getApiInventorySerials", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "invoiceId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "in_stock" }, { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySerialsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiInventorySerialsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Register serial numbers against a batch.", "operationId": "postApiInventorySerials", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "type": "string" }, "serials": { "type": "array", "items": { "type": "string" } }, "rangePrefix": { "type": "string" }, "rangeStart": { "type": "integer" }, "rangeCount": { "type": "integer" }, "rangePad": { "type": "integer" }, "batchId": { "type": "string" }, "locationId": { "type": "string" }, "supplier": { "type": "string" }, "receivedDate": { "type": "string", "format": "date" }, "unitCost": { "type": "number" }, "notes": { "type": "string" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "serials": [ "SN-0001", "SN-0002" ], "rangePrefix": "INV-", "rangeStart": 1, "rangeCount": 3, "rangePad": 1, "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplier": "Karoo Fresh Holdings Ltd", "receivedDate": "2026-09-01", "unitCost": 2900.0, "notes": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "integer" }, "duplicates": { "type": "array", "items": { "type": "string" } }, "serials": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySerialsResponseItem" } } } }, "example": { "created": 1, "duplicates": [ "text" ], "serials": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "serialNumber": "INV-0001", "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplier": "Karoo Fresh Holdings Ltd", "receivedDate": "2026-09-01", "unitCost": 2900.0, "status": "sent", "soldDate": "2026-09-01", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "autoAssigned": false, "warrantyExpiry": "2026-09-30", "warrantyDaysRemaining": 30, "underWarranty": false, "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/serials/{id}": { "get": { "tags": [ "Inventory" ], "summary": "One serialised unit and its history.", "operationId": "getApiInventorySerialsById", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInventorySerialsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInventorySerialsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Inventory" ], "summary": "Remove a serial registered in error.", "operationId": "deleteApiInventorySerialsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/serials/lookup": { "get": { "tags": [ "Inventory" ], "summary": "Find a unit by its serial.", "operationId": "getApiInventorySerialsLookup", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "serial", "in": "query", "required": false, "schema": { "type": "string" }, "example": "SN-0001" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInventorySerialsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInventorySerialsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/serials/summary": { "get": { "tags": [ "Inventory" ], "summary": "Counts by status — in stock, sold, returned, scrapped.", "operationId": "getApiInventorySerialsSummary", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalSerials": { "type": "integer" }, "inStock": { "type": "integer" }, "sold": { "type": "integer" }, "returned": { "type": "integer" }, "scrapped": { "type": "integer" }, "underWarranty": { "type": "integer" }, "warrantyExpiringSoon": { "type": "integer" }, "unconfirmedAssignments": { "type": "integer" }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "stockQty": { "type": "number" }, "serialsOnHand": { "type": "integer" }, "serialsSold": { "type": "integer" }, "uncaptured": { "type": "integer" }, "orphanedSerials": { "type": "integer" } } } } } }, "example": { "totalSerials": 1, "inStock": 1, "sold": 1, "returned": 1, "scrapped": 1, "underWarranty": 1, "warrantyExpiringSoon": 1, "unconfirmedAssignments": 1, "products": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "stockQty": 3.0, "serialsOnHand": 1, "serialsSold": 1, "uncaptured": 1, "orphanedSerials": 1 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/serials/assign": { "post": { "tags": [ "Inventory" ], "summary": "Assign serials to a document line at despatch.", "operationId": "postApiInventorySerialsAssign", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "serialIds": { "type": "array", "items": { "type": "string" } }, "productId": { "type": "string" } } }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "serialIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySerialsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiInventorySerialsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/serials/{id}/scrap": { "post": { "tags": [ "Inventory" ], "summary": "Write a unit off. Drains its OWN batch by one at that batch's cost — specific identification, which is the point of a serial — and posts DR 5070 / CR 1310. Only from in_stock.", "operationId": "postApiInventorySerialsByIdScrap", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventorySerialsByIdScrapRequest" }, "example": { "notes": "Water damage" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInventorySerialsResponseItem" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventorySerialsByIdScrapResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/serials/{id}/return": { "post": { "tags": [ "Inventory" ], "summary": "Return a unit to stock. A returned unit is back on the shelf only if a credit note restocked it.", "operationId": "postApiInventorySerialsByIdReturn", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventorySerialsByIdScrapRequest" }, "example": { "notes": "Customer return, resold as open-box" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInventorySerialsResponseItem" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventorySerialsByIdScrapResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/adjustment-reasons": { "get": { "tags": [ "Inventory" ], "summary": "The business's adjustment reasons — the defaults and its own — and whether an adjustment must give one.", "operationId": "getApiInventoryAdjustmentReasons", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInventoryAdjustmentReasonsResponse" }, "example": { "reasons": [ { "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "builtIn": true } ], "requireReason": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Add one of the business's own adjustment reasons.", "operationId": "postApiInventoryAdjustmentReasons", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryAdjustmentReasonsRequest" }, "example": { "label": "Warranty return" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInventoryAdjustmentReasonsResponse" }, "example": { "reasons": [ { "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "builtIn": true } ], "requireReason": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/reports/adjustments-by-reason": { "get": { "tags": [ "Inventory" ], "summary": "Adjustments by reason over a date range (dateFrom, dateTo): what each reason added and took away; the rows add up to every adjustment.", "operationId": "getApiInventoryReportsAdjustmentsByReason", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-10-31" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "dateFrom": { "type": "string", "format": "date" }, "dateTo": { "type": "string", "format": "date" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "adjustments": { "type": "integer" }, "qtyIn": { "type": "number" }, "qtyOut": { "type": "number" }, "value": { "type": "number" } } } }, "adjustments": { "type": "integer" }, "value": { "type": "number" } } }, "example": { "dateFrom": "2026-09-01", "dateTo": "2026-09-30", "rows": [ { "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "adjustments": 1, "qtyIn": 1.0, "qtyOut": 1.0, "value": 10005.0 } ], "adjustments": 1, "value": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/bins": { "get": { "tags": [ "Inventory" ], "summary": "The bins inside the company's locations, with how many products each keeps.", "operationId": "getApiInventoryBins", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventoryBinsResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "products": 1 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Add a bin to a location.", "operationId": "postApiInventoryBins", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "example": { "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "A-01", "name": "Power tools" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventoryBinsResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "products": 1 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/products/{id}/bin": { "put": { "tags": [ "Inventory" ], "summary": "Keep a product in a bin at a location, or clear it.", "operationId": "putApiInventoryProductsByIdBin", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string" }, "binId": { "type": "string" } } }, "example": { "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "binId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/cycle-counts": { "get": { "tags": [ "Inventory" ], "summary": "Cycle-count schedules, each raising one stock take a period.", "operationId": "getApiInventoryCycleCounts", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventoryCycleCountsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiInventoryCycleCountsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Schedule a cycle count — weekly, monthly or quarterly; all of a location, one ABC class or one bin. This period's count is raised at once.", "operationId": "postApiInventoryCycleCounts", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string" }, "cadence": { "type": "string" }, "scope": { "type": "string" }, "abcClass": { "type": "string" }, "binId": { "type": "string" }, "active": { "type": "boolean" } } }, "example": { "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "cadence": "monthly", "scope": "abc", "abcClass": "A", "binId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "active": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventoryCycleCountsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiInventoryCycleCountsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/cycle-counts/{id}": { "delete": { "tags": [ "Inventory" ], "summary": "Stop a cycle-count schedule; counts already raised stay.", "operationId": "deleteApiInventoryCycleCountsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/pick-list": { "get": { "tags": [ "Inventory" ], "summary": "The pick list: what every open delivery note and open sales order asks the stock room to fetch, by location and bin, with on-hand beside it.", "operationId": "getApiInventoryPickList", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "binCode": { "type": "string" }, "quantity": { "type": "number" }, "onHand": { "type": "number" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "documentId": { "type": "string" }, "number": { "type": "string" }, "documentType": { "type": "string" }, "contactName": { "type": "string" }, "lineId": { "type": "string" }, "quantity": { "type": "number" } } } } } } }, "notes": { "type": "integer" }, "orders": { "type": "integer" } } }, "example": { "lines": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "binCode": "CT-001", "quantity": 3.0, "onHand": 1.0, "sources": [ { "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "INV-0001", "documentType": "invoice", "contactName": "Karoo Fresh Holdings Ltd", "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0 } ] } ], "notes": 1, "orders": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/backorders": { "get": { "tags": [ "Inventory" ], "summary": "Open sales orders still owing something after a pick, line by line.", "operationId": "getApiInventoryBackorders", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventoryBackordersResponseItem" } }, "example": [ { "orderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "INV-0001", "contactName": "Karoo Fresh Holdings Ltd", "backordered": 1.0, "lines": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "ordered": 1.0, "backordered": 1.0 } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/pick-list/orders/{id}/pick": { "post": { "tags": [ "Inventory" ], "summary": "Pick a sales order: a delivery note is raised for what was picked, and what was not stays owed as a backorder. Replay-safe on clientId.", "operationId": "postApiInventoryPickListOrdersByIdPick", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string" }, "picked": { "type": "number" } } } }, "clientId": { "type": "string" } } }, "example": { "lines": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "picked": 3.0 } ], "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "noteId": { "type": "string" }, "noteNumber": { "type": "string" }, "backorder": { "$ref": "#/components/schemas/GetApiInventoryBackordersResponseItem" } } }, "example": { "noteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "noteNumber": "INV-0001", "backorder": { "orderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "number": "INV-0001", "contactName": "Karoo Fresh Holdings Ltd", "backordered": 1.0, "lines": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "ordered": 1.0, "backordered": 1.0 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/stock-takes": { "get": { "tags": [ "Inventory" ], "summary": "Stock takes and their variance.", "operationId": "getApiInventoryStockTakes", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryStockTakesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "name": "Karoo Fresh Holdings Ltd", "status": "sent", "startedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "lineCount": 3, "totalVariance": 10005.0, "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "sku": "LEN-TP-14G4", "expectedQty": 3.0, "countedQty": 3.0, "variance": 1.0 } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Open a stock take.", "operationId": "postApiInventoryStockTakes", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "locationId": { "type": "string" }, "category": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "category": "Office supplies" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryStockTakesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryStockTakesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/stock-takes/{id}": { "get": { "tags": [ "Inventory" ], "summary": "One stock take with its counted lines.", "operationId": "getApiInventoryStockTakesById", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryStockTakesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryStockTakesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/stock-takes/{id}/lines": { "put": { "tags": [ "Inventory" ], "summary": "Save counts. The variance is written WHEN COUNTS ARE SAVED, not only at commit — the list used to tell a supervisor a count with eight units missing was clean.", "operationId": "putApiInventoryStockTakesByIdLines", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "counts": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string" }, "countedQty": { "type": "number" } } } } } }, "example": { "counts": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "countedQty": 2.0 } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryStockTakesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryStockTakesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/stock-takes/{id}/commit": { "post": { "tags": [ "Inventory" ], "summary": "Post the variance as adjustments.", "operationId": "postApiInventoryStockTakesByIdCommit", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryStockTakesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryStockTakesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/stock-takes/{id}/cancel": { "post": { "tags": [ "Inventory" ], "summary": "Abandon a stock take.", "operationId": "postApiInventoryStockTakesByIdCancel", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryStockTakesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryStockTakesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/boms": { "get": { "tags": [ "Inventory" ], "summary": "Assembly recipes. These are V96's simple recipes at the Business tier; the deep BOM work is /api/bom on the Manufacturing plan.", "operationId": "getApiInventoryBoms", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryBomsResponse" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiInventoryBomsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Create a recipe.", "operationId": "postApiInventoryBoms", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryBomsRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryBomsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryBomsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/boms/{id}": { "get": { "tags": [ "Inventory" ], "summary": "One recipe.", "operationId": "getApiInventoryBomsById", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryBomsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryBomsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Inventory" ], "summary": "Change a recipe.", "operationId": "putApiInventoryBomsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryBomsRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryBomsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryBomsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Inventory" ], "summary": "Delete a recipe.", "operationId": "deleteApiInventoryBomsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/boms/{id}/cost": { "get": { "tags": [ "Inventory" ], "summary": "What the recipe costs at current batch costs.", "operationId": "getApiInventoryBomsByIdCost", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "qty", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "bomId": { "type": "string" }, "runsNeeded": { "type": "integer" }, "qtyToBuild": { "type": "number" }, "components": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "qtyPer": { "type": "number" }, "scrapPercent": { "type": "number" }, "qtyRequired": { "type": "number" }, "available": { "type": "integer" }, "shortfall": { "type": "number" }, "unitCost": { "type": "number" }, "lineCost": { "type": "number" }, "isTracked": { "type": "boolean" }, "hasOwnBom": { "type": "boolean" } } } }, "componentCost": { "type": "number" }, "labourCost": { "type": "number" }, "overheadCost": { "type": "number" }, "totalCost": { "type": "number" }, "unitCost": { "type": "number" }, "maxBuildable": { "type": "number" }, "blockers": { "type": "array", "items": { "type": "object" } }, "canBuild": { "type": "boolean" } } }, "example": { "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "runsNeeded": 1, "qtyToBuild": 1.0, "components": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "qtyPer": 1.0, "scrapPercent": 15.0, "qtyRequired": 1.0, "available": 1, "shortfall": 1.0, "unitCost": 2900.0, "lineCost": 10005.0, "isTracked": true, "hasOwnBom": false } ], "componentCost": 10005.0, "labourCost": 10005.0, "overheadCost": 10005.0, "totalCost": 10005.0, "unitCost": 2900.0, "maxBuildable": 1.0, "blockers": [], "canBuild": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/boms/using/{productId}": { "get": { "tags": [ "Inventory" ], "summary": "Which recipes use this component.", "operationId": "getApiInventoryBomsUsingByProductId", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryBomsResponse" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiInventoryBomsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/disassemblies": { "get": { "tags": [ "Inventory" ], "summary": "Products broken back into their parts. Newest first, bounded.", "operationId": "getApiInventoryDisassemblies", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInventoryDisassembliesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "qty": 3.0, "parentValue": 10005.0, "partsValue": 10005.0, "residue": 1.0, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "brokenAt": "2026-09-01T09:15:00Z", "parts": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "qtyRecovered": 1.0, "unitCost": 2900.0, "value": 10005.0, "batchId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Break a product back into its parts using its recipe — a case of 24 into singles, a returned unit into spares. The parts inherit exactly what the parent's own batches cost, split by their share of the recipe's material value; scrap is NOT recovered, because it was consumed making the thing. Both legs are 1310, so the only ledger entry is the rounding a four-place unit cost cannot hold, written off to 5070 so the batch total and 1310 stay tied exactly.", "operationId": "postApiInventoryDisassemblies", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bomId": { "type": "string" }, "qty": { "type": "number" }, "locationId": { "type": "string" }, "reference": { "type": "string" }, "notes": { "type": "string" } } }, "example": { "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qty": 2.0, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryDisassembliesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryDisassembliesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/disassemblies/{id}": { "get": { "tags": [ "Inventory" ], "summary": "One disassembly, with the parts it recovered and what each was given.", "operationId": "getApiInventoryDisassembliesById", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryDisassembliesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiInventoryDisassembliesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/builds": { "get": { "tags": [ "Inventory" ], "summary": "Assembly builds.", "operationId": "getApiInventoryBuilds", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventoryBuildsByIdResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomName": "Karoo Fresh Holdings Ltd", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyBuilt": 1.0, "status": "sent", "componentCost": 10005.0, "labourCost": 10005.0, "overheadCost": 10005.0, "totalCost": 10005.0, "unitCost": 2900.0, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "builtAt": "2026-09-01T09:15:00Z", "lines": [ { "componentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentName": "Karoo Fresh Holdings Ltd", "qtyRequired": 1.0, "qtyConsumed": 1.0, "unitCost": 2900.0, "totalCost": 10005.0, "short": false } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "summary": "Build assemblies from components. A short build is REFUSED, naming what is short and what maxBuildable says can be built now — costing a shortfall at list price once put the sum of batch values R61 441 above 1310 with no entry that could close it.", "operationId": "postApiInventoryBuilds", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bomId": { "type": "string" }, "qtyToBuild": { "type": "number" }, "locationId": { "type": "string" }, "reference": { "type": "string" }, "notes": { "type": "string" } } }, "example": { "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyToBuild": 2.0, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "build": { "$ref": "#/components/schemas/GetApiInventoryBuildsByIdResponse" }, "shortComponents": { "type": "array", "items": { "type": "string" } } } }, "example": { "build": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomName": "Karoo Fresh Holdings Ltd", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyBuilt": 1.0, "status": "sent", "componentCost": 10005.0, "labourCost": 10005.0, "overheadCost": 10005.0, "totalCost": 10005.0, "unitCost": 2900.0, "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "builtAt": "2026-09-01T09:15:00Z", "lines": [ { "componentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentName": "Karoo Fresh Holdings Ltd", "qtyRequired": 1.0, "qtyConsumed": 1.0, "unitCost": 2900.0, "totalCost": 10005.0, "short": false } ] }, "shortComponents": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/builds/{id}": { "get": { "tags": [ "Inventory" ], "summary": "One build and what it consumed.", "operationId": "getApiInventoryBuildsById", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInventoryBuildsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInventoryBuildsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/inventory/builds/{id}/cancel": { "post": { "tags": [ "Inventory" ], "summary": "Reverse a build, returning components to their layers.", "operationId": "postApiInventoryBuildsByIdCancel", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiInventoryBuildsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiInventoryBuildsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards": { "get": { "tags": [ "Job cards" ], "summary": "Job cards, server-paged and server-filtered. It used to fetch one page of 100 and filter client-side, so a workshop lost its history after a fortnight.", "operationId": "getApiJobCards", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "in_progress" }, { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" }, { "name": "contactId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "technicianId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "search", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" }, { "name": "scheduled", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" }, { "name": "priority", "in": "query", "required": false, "schema": { "type": "string" }, "example": "normal" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponse" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobNumber": "JC-0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "title": "Karoo Fresh Holdings Ltd", "workRequested": "text", "siteAddress": "12 Long Street, Cape Town, 8001", "siteContactName": "Karoo Fresh Holdings Ltd", "siteContactPhone": "+27 82 555 0143", "priority": "normal", "status": "sent", "scheduledStart": "2026-09-01", "scheduledEnd": "2026-09-30", "actualStart": "2026-09-01", "actualEnd": "2026-09-30", "quotedAmount": 10005.0, "currency": "ZAR", "sourceQuoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceQuoteNumber": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "invoicedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "signOffName": "Karoo Fresh Holdings Ltd", "signOffRole": "Accountant", "signOffSignature": "text", "signOffSignatureAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "signOffNotes": "Budget deferred to the next financial year.", "signOffAt": "2026-09-01T09:15:00Z", "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z", "technicians": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "isLead": false } ], "labour": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "technicianName": "Thandi Mokoena", "workDate": "2026-09-01", "hours": 3.0, "chargeRate": 15.0, "costRate": 15.0, "billable": true, "notes": "Budget deferred to the next financial year.", "timeEntryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "parts": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "partCode": "CT-001", "qty": 3.0, "unitCost": 2900.0, "unitPrice": 2900.0, "billable": true, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "issued": false, "issuedAt": "2026-09-01T09:15:00Z", "issuedQty": 3.0, "stockMovementId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stockTracked": false } ], "costs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costType": "standard", "description": "Consulting services — August 2026", "amount": 10005.0, "markupPercent": 15.0, "km": 1.0, "ratePerKm": 1.0, "billable": true, "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "incurredOn": "2026-09-01", "sourceExpenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceBillId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceReference": "INV-0001" } ], "statusHistory": [ { "fromStatus": "sent", "toStatus": "sent", "note": "Budget deferred to the next financial year.", "changedByName": "Karoo Fresh Holdings Ltd", "at": "2026-09-01T09:15:00Z" } ], "photos": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "phase": "text", "caption": "Serial plate before fitting", "sequence": 1, "takenByName": "Karoo Fresh Holdings Ltd", "takenAt": "2026-09-01T09:15:00Z" } ], "costing": { "labourHours": 3.0, "labourCost": 10005.0, "labourBillable": 1.0, "partsCost": 10005.0, "partsBillable": 1.0, "otherCost": 10005.0, "otherBillable": 1.0, "actualCost": 10005.0, "billableValue": 10005.0, "quotedAmount": 10005.0, "quoteVariance": 1.0, "margin": 1.0, "marginPercent": 15.0 }, "allowedNextStatuses": [ "text" ] } ], "total": 42, "page": 1, "limit": 20, "totalPages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Job cards" ], "summary": "Raise a job. Accepts a client-minted id, which is what makes offline capture replayable — the CARD queues, but issuing parts and converting stay online-only.", "operationId": "postApiJobCards", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "contactId": { "type": "string" }, "title": { "type": "string" }, "workRequested": { "type": "string" }, "siteAddress": { "type": "string" }, "siteContactName": { "type": "string" }, "siteContactPhone": { "type": "string" }, "priority": { "type": "string" }, "scheduledStart": { "type": "string", "format": "date" }, "scheduledEnd": { "type": "string", "format": "date" }, "quotedAmount": { "type": "number" }, "currency": { "type": "string" }, "sourceQuoteId": { "type": "string" }, "notes": { "type": "string" }, "technicianUserIds": { "type": "array", "items": { "type": "string" } }, "leadUserId": { "type": "string" }, "serialId": { "type": "string" }, "serialNumber": { "type": "string" }, "serviceContractId": { "type": "string" } } }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "title": "Karoo Fresh Holdings Ltd", "workRequested": "Replace element and thermostat", "siteAddress": "12 Long Street, Cape Town, 8001", "siteContactName": "Karoo Fresh Holdings Ltd", "siteContactPhone": "+27 82 555 0143", "priority": "normal", "scheduledStart": "2026-09-01", "scheduledEnd": "2026-09-30", "quotedAmount": 10005.0, "currency": "ZAR", "sourceQuoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "technicianUserIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "leadUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "serialId": "5c2d8e14-6f3a-4b97-a0d1-7e9f2c4b6a18", "serialNumber": "CB-24-0007", "serviceContractId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}": { "get": { "tags": [ "Job cards" ], "summary": "One job with its labour, parts, costs and sign-off.", "operationId": "getApiJobCardsById", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Job cards" ], "summary": "Update a job.", "operationId": "putApiJobCardsById", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "title": { "type": "string" }, "workRequested": { "type": "string" }, "siteAddress": { "type": "string" }, "siteContactName": { "type": "string" }, "siteContactPhone": { "type": "string" }, "priority": { "type": "string" }, "scheduledStart": { "type": "string", "format": "date" }, "scheduledEnd": { "type": "string", "format": "date" }, "actualStart": { "type": "string", "format": "date" }, "actualEnd": { "type": "string", "format": "date" }, "quotedAmount": { "type": "number" }, "currency": { "type": "string" }, "notes": { "type": "string" }, "serialId": { "type": "string" }, "serialNumber": { "type": "string" } } }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "title": "Karoo Fresh Holdings Ltd", "workRequested": "Replace element, thermostat and drip tray", "siteAddress": "12 Long Street, Cape Town, 8001", "siteContactName": "Karoo Fresh Holdings Ltd", "siteContactPhone": "+27 82 555 0143", "priority": "normal", "scheduledStart": "2026-09-01", "scheduledEnd": "2026-09-30", "actualStart": "2026-09-01", "actualEnd": "2026-09-30", "quotedAmount": 10005.0, "currency": "ZAR", "notes": "Budget deferred to the next financial year.", "serialId": "5c2d8e14-6f3a-4b97-a0d1-7e9f2c4b6a18", "serialNumber": "CB-24-0007" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Job cards" ], "summary": "Delete a job.", "operationId": "deleteApiJobCardsById", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/status": { "post": { "tags": [ "Job cards" ], "summary": "Move a job through open, in progress, awaiting parts, ready to invoice, closed.", "operationId": "postApiJobCardsByIdStatus", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "note": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "status": "awaiting_parts", "note": "Budget deferred to the next financial year.", "clientId": "9b2e4f61-7c3a-4d58-8e10-5a6b7c8d9e0f" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/summary": { "get": { "tags": [ "Job cards" ], "summary": "The board's tiles. Windowed to twelve months plus every open job.", "operationId": "getApiJobCardsSummary", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "openJobs": { "type": "integer" }, "scheduledToday": { "type": "integer" }, "awaitingParts": { "type": "integer" }, "completedNotInvoiced": { "type": "integer" }, "wipValue": { "type": "number" }, "wipCost": { "type": "number" }, "invoicedThisMonth": { "type": "number" }, "averageMarginPercent": { "type": "number" }, "windowMonths": { "type": "integer" }, "currency": { "type": "string" } } }, "example": { "openJobs": 1, "scheduledToday": 1, "awaitingParts": 1, "completedNotInvoiced": 1, "wipValue": 10005.0, "wipCost": 10005.0, "invoicedThisMonth": 1.0, "averageMarginPercent": 15.0, "windowMonths": 12, "currency": "ZAR" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/labour": { "post": { "tags": [ "Job cards" ], "summary": "Book labour. The rates default from users.default_charge_rate and default_cost_rate — before those existed, cost_rate defaulted to zero and every job reported 100% margin.", "operationId": "postApiJobCardsByIdLabour", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "userId": { "type": "string" }, "technicianName": { "type": "string" }, "workDate": { "type": "string", "format": "date" }, "hours": { "type": "number" }, "chargeRate": { "type": "number" }, "costRate": { "type": "number" }, "billable": { "type": "boolean" }, "notes": { "type": "string" }, "basis": { "type": "string" }, "units": { "type": "null" }, "unitLabel": { "type": "null" }, "earningTypeId": { "type": "null" } } }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "technicianName": "Thandi Mokoena", "workDate": "2026-09-30", "hours": 2.0, "chargeRate": 650.0, "costRate": 320.0, "billable": true, "notes": "Budget deferred to the next financial year.", "basis": "hours", "units": null, "unitLabel": null, "earningTypeId": null } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/labour/{lineId}": { "put": { "tags": [ "Job cards" ], "summary": "Correct a labour line.", "operationId": "putApiJobCardsByIdLabourByLineId", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "technicianName": { "type": "string" }, "workDate": { "type": "string", "format": "date" }, "hours": { "type": "number" }, "chargeRate": { "type": "number" }, "costRate": { "type": "number" }, "billable": { "type": "boolean" }, "notes": { "type": "string" }, "basis": { "type": "string" }, "units": { "type": "null" }, "unitLabel": { "type": "null" }, "earningTypeId": { "type": "null" } } }, "example": { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "technicianName": "Thandi Mokoena", "workDate": "2026-09-01", "hours": 4.0, "chargeRate": 15.0, "costRate": 15.0, "billable": true, "notes": "Budget deferred to the next financial year.", "basis": "hours", "units": null, "unitLabel": null, "earningTypeId": null } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Job cards" ], "summary": "Remove a labour line.", "operationId": "deleteApiJobCardsByIdLabourByLineId", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/labour/import-time": { "post": { "tags": [ "Job cards" ], "summary": "Pull hours in from time tracking. Imports only APPROVED entries — the project invoicer always required it and this path did not, so approvals were bypassed by whichever of the two billing paths somebody used.", "operationId": "postApiJobCardsByIdLabourImportTime", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "timeEntryIds": { "type": "array", "items": { "type": "string" } }, "chargeRate": { "type": "number" }, "costRate": { "type": "number" } } }, "example": { "timeEntryIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "chargeRate": 15.0, "costRate": 15.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "integer" }, "skipped": { "type": "integer" } } }, "example": { "imported": 1, "skipped": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/parts": { "post": { "tags": [ "Job cards" ], "summary": "Add a part to the job, before it is issued.", "operationId": "postApiJobCardsByIdParts", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsByIdPartsRequest" }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Captured during the August review", "partCode": "CT-001", "qty": 2.0, "unitCost": 2900.0, "unitPrice": 2900.0, "billable": true, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/parts/{lineId}": { "put": { "tags": [ "Job cards" ], "summary": "Change a part line.", "operationId": "putApiJobCardsByIdPartsByLineId", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsByIdPartsRequest" }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "partCode": "CT-001", "qty": 2.0, "unitCost": 2900.0, "unitPrice": 2900.0, "billable": true, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Job cards" ], "summary": "Remove a part line.", "operationId": "deleteApiJobCardsByIdPartsByLineId", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/parts/{lineId}/issue": { "post": { "tags": [ "Job cards" ], "summary": "Issue the part from stock at batch cost. What is in the van is out of the storeroom in the figures as well as in fact.", "operationId": "postApiJobCardsByIdPartsByLineIdIssue", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" } } }, "example": { "clientId": "9b2e4f61-7c3a-4d58-8e10-5a6b7c8d9e0f" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "qtyIssued": { "type": "integer" }, "unitCost": { "type": "string" }, "balanceAfter": { "type": "string" }, "warning": { "type": "string" }, "jobCardId": { "type": "string" }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "locationSource": { "type": "string" }, "locationMessage": { "type": "string" } } }, "example": { "status": "issued", "qtyIssued": 3, "unitCost": "text", "balanceAfter": "text", "warning": "text", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "locationSource": "referral", "locationMessage": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/parts/{lineId}/return": { "post": { "tags": [ "Job cards" ], "summary": "Return an unused part to stock.", "operationId": "postApiJobCardsByIdPartsByLineIdReturn", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/costs": { "post": { "tags": [ "Job cards" ], "summary": "Add an on-cost typed by hand — a subcontractor, a callout fee.", "operationId": "postApiJobCardsByIdCosts", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsByIdCostsRequest" }, "example": { "costType": "other", "description": "Crane hire", "amount": 4200.0, "markupPercent": 10.0, "km": 1.0, "ratePerKm": 1.0, "billable": true, "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "incurredOn": "2026-09-01" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/costs/allocate": { "post": { "tags": [ "Job cards" ], "summary": "Allocate a real expense or bill to the job. JobCostAllocation is the single writer of both halves — the column on the purchase and the mirroring cost line — because either alone is a defect with a plausible screen.", "operationId": "postApiJobCardsByIdCostsAllocate", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expenseIds": { "type": "array", "items": { "type": "string" } }, "billIds": { "type": "array", "items": { "type": "string" } }, "billable": { "type": "boolean" }, "markupPercent": { "type": "number" }, "costType": { "type": "string" } } }, "example": { "expenseIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "billIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "billable": true, "markupPercent": 15.0, "costType": "subcontractor" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "allocated": { "type": "integer" }, "skipped": { "type": "array", "items": { "type": "string" } }, "card": { "$ref": "#/components/schemas/PostApiJobCardsResponse" } } }, "example": { "allocated": 1, "skipped": [ "text" ], "card": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobNumber": "JC-0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "title": "Karoo Fresh Holdings Ltd", "workRequested": "text", "siteAddress": "12 Long Street, Cape Town, 8001", "siteContactName": "Karoo Fresh Holdings Ltd", "siteContactPhone": "+27 82 555 0143", "priority": "normal", "status": "sent", "scheduledStart": "2026-09-01", "scheduledEnd": "2026-09-30", "actualStart": "2026-09-01", "actualEnd": "2026-09-30", "quotedAmount": 10005.0, "currency": "ZAR", "sourceQuoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceQuoteNumber": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "invoicedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "signOffName": "Karoo Fresh Holdings Ltd", "signOffRole": "Accountant", "signOffSignature": "text", "signOffSignatureAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "signOffNotes": "Budget deferred to the next financial year.", "signOffAt": "2026-09-01T09:15:00Z", "notes": "Budget deferred to the next financial year.", "createdAt": "2026-09-01T09:15:00Z", "technicians": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "isLead": false } ], "labour": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "technicianName": "Thandi Mokoena", "workDate": "2026-09-01", "hours": 3.0, "chargeRate": 15.0, "costRate": 15.0, "billable": true, "notes": "Budget deferred to the next financial year.", "timeEntryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "parts": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "partCode": "CT-001", "qty": 3.0, "unitCost": 2900.0, "unitPrice": 2900.0, "billable": true, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "issued": false, "issuedAt": "2026-09-01T09:15:00Z", "issuedQty": 3.0, "stockMovementId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stockTracked": false } ], "costs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costType": "standard", "description": "Consulting services — August 2026", "amount": 10005.0, "markupPercent": 15.0, "km": 1.0, "ratePerKm": 1.0, "billable": true, "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "incurredOn": "2026-09-01", "sourceExpenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceBillId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceReference": "INV-0001" } ], "statusHistory": [ { "fromStatus": "sent", "toStatus": "sent", "note": "Budget deferred to the next financial year.", "changedByName": "Karoo Fresh Holdings Ltd", "at": "2026-09-01T09:15:00Z" } ], "photos": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "phase": "text", "caption": "Serial plate before fitting", "sequence": 1, "takenByName": "Karoo Fresh Holdings Ltd", "takenAt": "2026-09-01T09:15:00Z" } ], "costing": { "labourHours": 3.0, "labourCost": 10005.0, "labourBillable": 1.0, "partsCost": 10005.0, "partsBillable": 1.0, "otherCost": 10005.0, "otherBillable": 1.0, "actualCost": 10005.0, "billableValue": 10005.0, "quotedAmount": 10005.0, "quoteVariance": 1.0, "margin": 1.0, "marginPercent": 15.0 }, "allowedNextStatuses": [ "text" ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/costs/{lineId}": { "put": { "tags": [ "Job cards" ], "summary": "Change a cost line. An allocated purchase's AMOUNT is refused here and the response names where to correct it — what a job cost is a fact about the purchase; what the customer is charged is a decision about the job, so markup and billable stay editable.", "operationId": "putApiJobCardsByIdCostsByLineId", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsByIdCostsRequest" }, "example": { "costType": "other", "description": "Consulting services — August 2026", "amount": 10005.0, "markupPercent": 20.0, "km": 1.0, "ratePerKm": 1.0, "billable": true, "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "incurredOn": "2026-09-01" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Job cards" ], "summary": "Remove a cost line.", "operationId": "deleteApiJobCardsByIdCostsByLineId", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/allocatable-costs": { "get": { "tags": [ "Job cards" ], "summary": "Expenses and bills that could still be allocated to a job.", "operationId": "getApiJobCardsAllocatableCosts", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "reference": { "type": "string" }, "description": { "type": "string" }, "vendor": { "type": "string" }, "date": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "category": { "type": "string" }, "contactId": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "reference": "INV-0001", "description": "Consulting services — August 2026", "vendor": "Karoo Fresh Holdings Ltd", "date": "2026-09-01", "amount": 10005.0, "currency": "ZAR", "status": "sent", "category": "Office supplies", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/pay-types": { "get": { "tags": [ "Job cards" ], "summary": "The per-unit payroll earning types a labour line counted in units can be paid as (e.g. Bay installed). Names only, never a rate, so a job-cards role without payroll access can choose one.", "operationId": "getApiJobCardsPayTypes", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "unitLabel": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Bay installed", "unitLabel": "bay" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/technicians": { "get": { "tags": [ "Job cards" ], "summary": "Who can be assigned, with their default rates.", "operationId": "getApiJobCardsTechnicians", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiJobCardsTechniciansResponseItem" } }, "example": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "defaultChargeRate": 15.0, "defaultCostRate": 15.0, "defaultStockLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "defaultStockLocationName": "Karoo Fresh Holdings Ltd" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/technicians/{userId}/rates": { "put": { "tags": [ "Job cards" ], "summary": "Set a person's default charge and cost rates. Deliberately NOT a per-project-per-person rate table — users owns the figure for both modules.", "operationId": "putApiJobCardsTechniciansByUserIdRates", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultChargeRate": { "type": "number" }, "defaultCostRate": { "type": "number" }, "clearChargeRate": { "type": "boolean" }, "clearCostRate": { "type": "boolean" }, "defaultStockLocationId": { "type": "string" }, "clearStockLocation": { "type": "boolean" } } }, "example": { "defaultChargeRate": 650.0, "defaultCostRate": 320.0, "clearChargeRate": false, "clearCostRate": false, "defaultStockLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clearStockLocation": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiJobCardsTechniciansResponseItem" }, "example": { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "defaultChargeRate": 15.0, "defaultCostRate": 15.0, "defaultStockLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "defaultStockLocationName": "Karoo Fresh Holdings Ltd" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/technicians": { "post": { "tags": [ "Job cards" ], "summary": "Assign a technician to the job.", "operationId": "postApiJobCardsByIdTechnicians", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "isLead": { "type": "boolean" } } }, "example": { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isLead": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/technicians/{userId}": { "delete": { "tags": [ "Job cards" ], "summary": "Unassign a technician.", "operationId": "deleteApiJobCardsByIdTechniciansByUserId", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/sign-off": { "post": { "tags": [ "Job cards" ], "summary": "Capture the customer's signature. The strokes become a 1-bit PNG in object storage as an AttachmentKind.SIGNATURE — never base64 into the column, which tenantStorageBytes does not count.", "operationId": "postApiJobCardsByIdSignOff", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signOffName": { "type": "string" }, "signOffRole": { "type": "string" }, "signOffSignature": { "type": "string" }, "signOffNotes": { "type": "string" }, "complete": { "type": "boolean" }, "clientId": { "type": "string" } } }, "example": { "signOffName": "Karoo Fresh Holdings Ltd", "signOffRole": "Accountant", "signOffSignature": "", "signOffNotes": "Budget deferred to the next financial year.", "complete": true, "clientId": "9b2e4f61-7c3a-4d58-8e10-5a6b7c8d9e0f" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/convert": { "post": { "tags": [ "Job cards" ], "summary": "Raise the invoice — the final one, or a deposit or progress stage that leaves the job open (stage, percent or lineIds); the final deducts each percentage stage. Charges the VAT the tenant may actually charge — a company with no vat_number is not registered, and part lines bill at their own product's rate rather than a flat 15%.", "operationId": "postApiJobCardsByIdConvert", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "override": { "type": "boolean" }, "issueDate": { "type": "string", "format": "date" }, "paymentTermsDays": { "type": "integer" }, "vatRate": { "type": "number" }, "summariseLabour": { "type": "boolean" }, "stage": { "type": "string" }, "percent": { "type": "number" }, "lineIds": { "type": "array", "items": { "type": "object" } } } }, "example": { "override": false, "issueDate": "2026-08-26", "paymentTermsDays": 30, "vatRate": 15.0, "summariseLabour": false, "stage": "deposit", "percent": 30.0, "lineIds": [] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "linesCreated": { "type": "integer" }, "total": { "type": "number" }, "currency": { "type": "string" }, "stage": { "type": "string" } } }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "linesCreated": 1, "total": 10005.0, "currency": "ZAR", "stage": "deposit" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/report": { "get": { "tags": [ "Job cards" ], "summary": "The customer's job report — what was done, what was used, and the signature.", "operationId": "getApiJobCardsByIdReport", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/checklist-templates": { "get": { "tags": [ "Job cards" ], "summary": "The company's checklist templates: each job type's required items and certificate title.", "operationId": "getApiJobCardsChecklistTemplates", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsChecklistTemplatesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "items": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd", "kind": "standard", "required": true } ], "certificateTitle": "Karoo Fresh Holdings Ltd" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Job cards" ], "summary": "Create a checklist template. Each item is a tick, text, a number or a photo, and required unless it says not.", "operationId": "postApiJobCardsChecklistTemplates", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "certificateTitle": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "kind": { "type": "string" }, "required": { "type": "boolean" } } } } } }, "example": { "name": "Gas safety", "certificateTitle": "Gas Installation Certificate of Compliance", "items": [ { "label": "Isolation valve fitted", "kind": "tick" }, { "label": "Gas pressure (kPa)", "kind": "number" }, { "label": "Customer briefed", "kind": "tick", "required": false } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsChecklistTemplatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsChecklistTemplatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/checklist-templates/{templateId}": { "put": { "tags": [ "Job cards" ], "summary": "Change a checklist template. A job that already carries it keeps the items it was given.", "operationId": "putApiJobCardsChecklistTemplatesByTemplateId", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "certificateTitle": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "kind": { "type": "string" } } } } } }, "example": { "name": "Gas safety", "certificateTitle": "Gas Installation Certificate of Compliance", "items": [ { "label": "Isolation valve fitted", "kind": "tick" }, { "label": "Gas pressure (kPa)", "kind": "number" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsChecklistTemplatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsChecklistTemplatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/checklists": { "post": { "tags": [ "Job cards" ], "summary": "Put a template's checklist on a job. A required item left open stops the job being completed.", "operationId": "postApiJobCardsByIdChecklists", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string" } } }, "example": { "templateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsByIdChecklistsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsByIdChecklistsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/checklists/{checklistId}/items/{key}": { "put": { "tags": [ "Job cards" ], "summary": "Answer one checklist item: tick it, or give its text, number or the id of one of the job's photographs.", "operationId": "putApiJobCardsByIdChecklistsByChecklistIdItemsByKey", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "checklistId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticked": { "type": "boolean" }, "value": { "type": "string" } } }, "example": { "ticked": false, "value": "2.8" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsByIdChecklistsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsByIdChecklistsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/checklists/{checklistId}/certificate": { "get": { "tags": [ "Job cards" ], "summary": "A checklist's certificate: its answered items under the template's certificate title.", "operationId": "getApiJobCardsByIdChecklistsByChecklistIdCertificate", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "checklistId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/on-the-way": { "post": { "tags": [ "Job cards" ], "summary": "The technician is on the way: tell the job's customer by email and WhatsApp, once per visit. Says what was sent, what was already sent for this visit, or why nobody could be told.", "operationId": "postApiJobCardsByIdOnTheWay", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "etaMinutes": { "type": "integer" } } }, "example": { "etaMinutes": 20 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "array", "items": { "type": "string" } }, "alreadyTold": { "type": "array", "items": { "type": "string" } }, "nothingBecause": { "type": "string" } } }, "example": { "sent": [ "text" ], "alreadyTold": [ "text" ], "nothingBecause": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/report/send": { "post": { "tags": [ "Job cards" ], "summary": "Email the customer their signed job report, with the PDF attached.", "operationId": "postApiJobCardsByIdReportSend", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchApiContactsByIdRequestBase" }, "example": { "email": "accounts@coastalcold.example" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean" }, "to": { "type": "string", "format": "date" }, "attached": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "sent": true, "to": "2026-09-30", "attached": true, "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/dispatch": { "get": { "tags": [ "Job cards" ], "summary": "The dispatcher's day or week - a lane per technician, work placed by the clock, clashes flagged. Layout is computed by shared/domain/jobcards/DispatchBoard.kt so the screen cannot paint an overlap the server would not see. window=day|week, date=ISO anchor; an unknown window is refused rather than widened.", "operationId": "getApiJobCardsDispatch", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "30" }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string" }, "fromDate": { "type": "string", "format": "date" }, "toDate": { "type": "string", "format": "date" }, "lanes": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "jobNumber": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "contactName": { "type": "string" }, "siteAddress": { "type": "string" }, "scheduledStart": { "type": "string", "format": "date" }, "scheduledEnd": { "type": "string", "format": "date" }, "technicianIds": { "type": "array", "items": { "type": "string" } } } } }, "unscheduledTotal": { "type": "integer" } } }, "example": { "window": "text", "fromDate": "2026-09-01", "toDate": "2026-09-01", "lanes": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ], "jobs": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobNumber": "JC-0001", "title": "Karoo Fresh Holdings Ltd", "status": "sent", "priority": "normal", "contactName": "Karoo Fresh Holdings Ltd", "siteAddress": "12 Long Street, Cape Town, 8001", "scheduledStart": "2026-09-01", "scheduledEnd": "2026-09-30", "technicianIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } ], "unscheduledTotal": 42 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/dispatch": { "post": { "tags": [ "Job cards" ], "summary": "Reschedule and reassign in ONE write - what a drag across the board is. Two calls would leave a job at a time nobody chose when the second failed. unassignUserId is what makes a drag out of a lane take the job off THAT technician only.", "operationId": "postApiJobCardsByIdDispatch", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledStart": { "type": "string" }, "scheduledEnd": { "type": "string" }, "assignUserId": { "type": "string" }, "unassignUserId": { "type": "string" } } }, "example": { "scheduledStart": "2026-08-27T08:00:00", "scheduledEnd": "2026-08-27T10:00:00", "assignUserId": "00000000-0000-0000-0000-000000000000", "unassignUserId": "00000000-0000-0000-0000-000000000000" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/stock-locations": { "get": { "tags": [ "Job cards" ], "summary": "The stock locations the van picker may offer. Served here on jobcards:view because a role holding only jobcards:* cannot call the inventory tree at all - the same reason /api/bom/products exists.", "operationId": "getApiJobCardsStockLocations", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "isVan": { "type": "boolean" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "type": "standard", "isVan": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/reports/wip": { "get": { "tags": [ "Job cards" ], "summary": "Work in progress — cost incurred and not yet billed. On a bad month it is most of a business's cash.", "operationId": "getApiJobCardsReportsWip", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiJobCardsReportsWipResponseRowsItem" } }, "totalCost": { "type": "number" }, "totalBillable": { "type": "number" }, "currency": { "type": "string" } } }, "example": { "rows": [ { "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobNumber": "JC-0001", "title": "Karoo Fresh Holdings Ltd", "contactName": "Karoo Fresh Holdings Ltd", "status": "sent", "ageDays": 30, "cost": 10005.0, "billable": 1.0 } ], "totalCost": 10005.0, "totalBillable": 10005.0, "currency": "ZAR" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/reports/profitability": { "get": { "tags": [ "Job cards" ], "summary": "Margin per job, measured against quotedAmount where the job came from an accepted quote.", "operationId": "getApiJobCardsReportsProfitability", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "groupBy", "in": "query", "required": false, "schema": { "type": "string" }, "example": "job" }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "includeCancelled", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "groupBy": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "jobCount": { "type": "integer" }, "quoted": { "type": "number" }, "cost": { "type": "number" }, "billable": { "type": "number" }, "margin": { "type": "number" }, "marginPercent": { "type": "number" }, "hours": { "type": "number" } } } }, "totalCost": { "type": "number" }, "totalBillable": { "type": "number" }, "totalMargin": { "type": "number" }, "currency": { "type": "string" } } }, "example": { "groupBy": "text", "rows": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd", "jobCount": 3, "quoted": 1.0, "cost": 10005.0, "billable": 1.0, "margin": 1.0, "marginPercent": 15.0, "hours": 3.0 } ], "totalCost": 10005.0, "totalBillable": 10005.0, "totalMargin": 10005.0, "currency": "ZAR" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/reports/sla": { "get": { "tags": [ "Job cards" ], "summary": "SLA met: each customer's (or technician's) jobs logged under a contract with targets, and how many met their response and resolution targets.", "operationId": "getApiJobCardsReportsSla", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "groupBy", "in": "query", "required": false, "schema": { "type": "string" }, "example": "customer" }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-12-01" }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-12-31" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "groupBy": { "type": "string" }, "dateFrom": { "type": "string", "format": "date" }, "dateTo": { "type": "string", "format": "date" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "jobs": { "type": "integer" }, "respondMet": { "type": "integer" }, "respondBreached": { "type": "integer" }, "resolveMet": { "type": "integer" }, "resolveBreached": { "type": "integer" } } } } } }, "example": { "groupBy": "text", "dateFrom": "2026-09-01", "dateTo": "2026-09-30", "rows": [ { "key": "text", "name": "Karoo Fresh Holdings Ltd", "jobs": 1, "respondMet": 1, "respondBreached": 1, "resolveMet": 1, "resolveBreached": 1 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/reports/by-status": { "get": { "tags": [ "Job cards" ], "summary": "Jobs by state, for the board's counts.", "operationId": "getApiJobCardsReportsByStatus", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" }, "billableValue": { "type": "number" } } } }, "total": { "type": "integer" }, "currency": { "type": "string" } } }, "example": { "rows": [ { "status": "sent", "label": "Karoo Fresh Holdings Ltd", "count": 3, "billableValue": 10005.0 } ], "total": 42, "currency": "ZAR" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/reports/completion-time": { "get": { "tags": [ "Job cards" ], "summary": "How long jobs take, from raised to closed.", "operationId": "getApiJobCardsReportsCompletionTime", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sampleSize": { "type": "integer" }, "averageDaysToComplete": { "type": "number" }, "averageDaysToInvoice": { "type": "number" }, "medianDaysToComplete": { "type": "number" }, "slowest": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiJobCardsReportsWipResponseRowsItem" } } } }, "example": { "sampleSize": 1, "averageDaysToComplete": 1.0, "averageDaysToInvoice": 1.0, "medianDaysToComplete": 1.0, "slowest": [ { "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobNumber": "JC-0001", "title": "Karoo Fresh Holdings Ltd", "contactName": "Karoo Fresh Holdings Ltd", "status": "sent", "ageDays": 30, "cost": 10005.0, "billable": 1.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/photos": { "get": { "tags": [ "Job cards" ], "summary": "The job's photographs. Ids, not bytes — fetch each through /api/files/{id}, because a job with twenty pictures would otherwise make this response tens of megabytes on a phone at a kerbside.", "operationId": "getApiJobCardsByIdPhotos", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsResponsePhotosItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "phase": "text", "caption": "Serial plate before fitting", "sequence": 1, "takenByName": "Karoo Fresh Holdings Ltd", "takenAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Job cards" ], "summary": "Attach a photograph. RAW BYTES, not base64 — a Compose camera hands the client a ByteArray on every target and base64 inflates a 4 MB photo by a third. An 'after' is refused while the job is draft or scheduled: it is almost always a mis-tagged before. Capped at 24 per job.", "operationId": "postApiJobCardsByIdPhotos", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "phase", "in": "query", "required": false, "description": "Which phase a photograph belongs to: `before`, `after` or `general`.", "schema": { "type": "string" }, "example": "before" }, { "name": "caption", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Board+before+work" }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "9b2e4f61-7c3a-4d58-8e10-5a6b7c8d9e0f" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/{id}/photos/{photoId}": { "delete": { "tags": [ "Job cards" ], "summary": "Unlink a photograph. Removes the LINK, not the stored file — a job-card screen is not where somebody should be able to destroy evidence.", "operationId": "deleteApiJobCardsByIdPhotosByPhotoId", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "photoId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/maintenance": { "get": { "tags": [ "Service contracts" ], "summary": "The tenant's contracts, with the next due date and the number of visits owed COMPUTED server-side by MaintenanceSchedule — the same object the generator uses, so the countdown cannot disagree with the date a job card appears on.", "operationId": "getApiJobCardsMaintenance", "description": "Requires the `job-cards:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiJobCardsMaintenanceResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "title": "Karoo Fresh Holdings Ltd", "workRequested": "text", "siteAddress": "12 Long Street, Cape Town, 8001", "siteContactName": "Karoo Fresh Holdings Ltd", "siteContactPhone": "+27 82 555 0143", "priority": "normal", "cadence": "text", "cadenceLabel": "Karoo Fresh Holdings Ltd", "anchorDate": "2026-09-01", "endsOn": "2026-09-01", "active": true, "leadUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leadUserName": "Karoo Fresh Holdings Ltd", "lastRaisedOn": "2026-09-01", "nextDueOn": "2026-09-01", "visitsOwed": 1, "visitsRaised": 1, "notes": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Service contracts" ], "summary": "Set up a contract. An unknown cadence is refused rather than defaulted: guessing would put a customer's quarterly inspection on a weekly footing.", "operationId": "postApiJobCardsMaintenance", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsMaintenanceRequest" }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "title": "Monthly generator service", "workRequested": "Quarterly service of the cold-room compressor", "siteAddress": "12 Long Street, Cape Town, 8001", "siteContactName": "Karoo Fresh Holdings Ltd", "siteContactPhone": "+27 82 555 0143", "priority": "normal", "cadence": "monthly", "anchorDate": "2026-01-31", "endsOn": "2026-09-01", "active": true, "leadUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "serialId": "5c2d8e14-6f3a-4b97-a0d1-7e9f2c4b6a18", "serialNumber": "CB-24-0007", "slaTargets": { "urgent": { "respondMinutes": 60, "resolveMinutes": 480 } }, "businessHours": { "open": "08:00", "close": "17:00", "days": [ 1, 2, 3, 4, 5 ], "skipPublicHolidays": true } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsMaintenanceResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsMaintenanceResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/maintenance/{id}": { "put": { "tags": [ "Service contracts" ], "summary": "Change a contract. active=false pauses it — it raises nothing whatever its dates say, and keeps its history.", "operationId": "putApiJobCardsMaintenanceById", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsMaintenanceRequest" }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "title": "Monthly generator service", "workRequested": "Quarterly service of the cold-room compressor", "siteAddress": "12 Long Street, Cape Town, 8001", "siteContactName": "Karoo Fresh Holdings Ltd", "siteContactPhone": "+27 82 555 0143", "priority": "normal", "cadence": "monthly", "anchorDate": "2026-01-31", "endsOn": "2026-09-01", "active": false, "leadUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "serialId": "5c2d8e14-6f3a-4b97-a0d1-7e9f2c4b6a18", "serialNumber": "CB-24-0007", "slaTargets": { "urgent": { "respondMinutes": 60, "resolveMinutes": 480 } }, "businessHours": { "open": "08:00", "close": "17:00", "days": [ 1, 2, 3, 4, 5 ], "skipPublicHolidays": true } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiJobCardsMaintenanceResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiJobCardsMaintenanceResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Service contracts" ], "summary": "End a contract. Does not touch the job cards it has already raised — those are real work, some of it invoiced.", "operationId": "deleteApiJobCardsMaintenanceById", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/job-cards/maintenance/{id}/raise": { "post": { "tags": [ "Service contracts" ], "summary": "Raise the visits this contract owes, now. EVERY owed visit, not just the newest: a monthly contract three visits behind owes three job cards. Idempotent by a partial unique index on (contract, due date), so two replicas cannot raise the same visit twice. The same code the maintenance-jobcards scheduled job runs.", "operationId": "postApiJobCardsMaintenanceByIdRaise", "description": "Requires the `job-cards:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "job-cards:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "raised": { "type": "integer" }, "jobNumbers": { "type": "array", "items": { "type": "string" } }, "skipped": { "type": "array", "items": { "type": "string" } } } }, "example": { "raised": 1, "jobNumbers": [ "JC-0001" ], "skipped": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/entries": { "get": { "tags": [ "Time tracking" ], "summary": "Time entries, server-paged and server-filtered. It used to return every entry the tenant had ever logged, with no limit and no filter, on every screen load.", "operationId": "getApiTimeTrackingEntries", "description": "Requires the `time-tracking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-31" }, { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "integer" }, "example": "1" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "projectName": { "type": "string" }, "client": { "type": "string" }, "description": { "type": "string" }, "workDate": { "type": "string", "format": "date" }, "hours": { "type": "number" }, "billable": { "type": "boolean" }, "approved": { "type": "boolean" }, "invoiceId": { "type": "string" }, "userId": { "type": "string" }, "userName": { "type": "string" }, "jobCardId": { "type": "string" }, "jobNumber": { "type": "string" }, "task": { "type": "string" }, "taskId": { "type": "string" }, "approvedByName": { "type": "string" }, "approvedAt": { "type": "string" }, "rateSnapshot": { "type": "number" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "projectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "projectName": "Karoo Fresh Holdings Ltd", "client": "text", "description": "Consulting services — August 2026", "workDate": "2026-09-01", "hours": 3.0, "billable": true, "approved": true, "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userName": "Thandi Mokoena", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobNumber": "JC-0001", "task": "text", "taskId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "approvedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "rateSnapshot": 1.0 } ], "total": 42, "page": 1, "limit": 100, "totalPages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Time tracking" ], "summary": "Log time. Amounts accept what people paste — \"1 500,50\" and \"R1500.50\" both parse.", "operationId": "postApiTimeTrackingEntries", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "description": { "type": "string" }, "workDate": { "type": "string", "format": "date" }, "hours": { "type": "number" }, "billable": { "type": "boolean" }, "task": { "type": "string" }, "taskId": { "type": "string" }, "rate": { "type": "number" }, "clientId": { "type": "string" } } }, "example": { "projectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Captured during the August review", "workDate": "2026-09-30", "hours": 2.0, "billable": true, "task": "Design", "taskId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rate": 850.0, "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpForecastsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/entries/{id}": { "put": { "tags": [ "Time tracking" ], "summary": "Correct an entry, so a mis-typed 8 hours need not be deleted and re-captured — and delete needs a permission capture does not.", "operationId": "putApiTimeTrackingEntriesById", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" }, "workDate": { "type": "string", "format": "date" }, "hours": { "type": "number" }, "billable": { "type": "boolean" }, "task": { "type": "string" }, "taskId": { "type": "string" }, "clearTaskId": { "type": "boolean" }, "rate": { "type": "number" }, "clearRate": { "type": "boolean" } } }, "example": { "description": "Consulting services — August 2026", "workDate": "2026-09-01", "hours": 6.0, "billable": true, "task": "Design", "taskId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clearTaskId": false, "rate": 15.0, "clearRate": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "updated" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Time tracking" ], "summary": "Delete an entry. Refused once it is billed or held by a job card.", "operationId": "deleteApiTimeTrackingEntriesById", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/entries/{id}/approve": { "put": { "tags": [ "Time tracking" ], "summary": "Approve one entry. Records who approved it and when — approval used to be a bare boolean with no actor, under an invoice to a customer.", "operationId": "putApiTimeTrackingEntriesByIdApprove", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approved": { "type": "boolean" } } }, "example": { "approved": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/entries/approve": { "post": { "tags": [ "Time tracking" ], "summary": "Approve many at once.", "operationId": "postApiTimeTrackingEntriesApprove", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entryIds": { "type": "array", "items": { "type": "string" } }, "approved": { "type": "boolean" } } }, "example": { "entryIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "approved": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "approved": { "type": "integer" }, "skipped": { "type": "array", "items": { "type": "string" } } } }, "example": { "approved": 1, "skipped": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/entries/{id}/bill": { "post": { "tags": [ "Time tracking" ], "summary": "Mark an entry billed. Refused for an entry a job card already holds.", "operationId": "postApiTimeTrackingEntriesByIdBill", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInvoicesByIdApplyDepositRequest" }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "billed" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/projects": { "get": { "tags": [ "Time tracking" ], "summary": "Projects, with budget hours, budget amount and actuals against them.", "operationId": "getApiTimeTrackingProjects", "description": "Requires the `time-tracking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contactId": { "type": "string" }, "hourlyRate": { "type": "number" }, "billable": { "type": "boolean" }, "active": { "type": "boolean" }, "budgetHours": { "type": "number" }, "budgetAmount": { "type": "number" }, "actualHours": { "type": "number" }, "billableHours": { "type": "number" }, "actualValue": { "type": "number" }, "unbilledValue": { "type": "number" }, "actualCost": { "type": "number" }, "disbursementCost": { "type": "number" }, "unbilledDisbursements": { "type": "number" }, "billingType": { "type": "string" }, "fixedFee": { "type": "number" }, "margin": { "type": "number" }, "budgetUsedPercent": { "type": "number" }, "ownerUserId": { "type": "string" }, "memberUserIds": { "type": "array", "items": { "type": "string" } }, "anyoneCanLogTime": { "type": "boolean" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hourlyRate": 15.0, "billable": true, "active": true, "budgetHours": 3.0, "budgetAmount": 10005.0, "actualHours": 3.0, "billableHours": 3.0, "actualValue": 10005.0, "unbilledValue": 10005.0, "actualCost": 10005.0, "disbursementCost": 10005.0, "unbilledDisbursements": 1.0, "billingType": "standard", "fixedFee": 1.0, "margin": 1.0, "budgetUsedPercent": 15.0, "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "memberUserIds": [ "8d2e4b17-0c3a-4f59-b6e2-91a7d5c3e804" ], "anyoneCanLogTime": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Time tracking" ], "summary": "Create a project. Whoever creates it owns it; time is logged on it by its owner, its members (memberUserIds), timetracking:edit, or anyone when anyoneCanLogTime is on (off unless sent).", "operationId": "postApiTimeTrackingProjects", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "contactId": { "type": "string" }, "hourlyRate": { "type": "number" }, "billable": { "type": "boolean" }, "budgetHours": { "type": "number" }, "budgetAmount": { "type": "number" }, "billingType": { "type": "string" }, "fixedFee": { "type": "number" }, "anyoneCanLogTime": { "type": "boolean" }, "memberUserIds": { "type": "array", "items": { "type": "object" } } } }, "example": { "name": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hourlyRate": 15.0, "billable": true, "budgetHours": 3.0, "budgetAmount": 10005.0, "billingType": "standard", "fixedFee": 1.0, "anyoneCanLogTime": false, "memberUserIds": [] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contactId": { "type": "string" }, "hourlyRate": { "type": "number" }, "billable": { "type": "boolean" }, "active": { "type": "boolean" }, "budgetHours": { "type": "number" }, "budgetAmount": { "type": "number" }, "actualHours": { "type": "number" }, "billableHours": { "type": "number" }, "actualValue": { "type": "number" }, "unbilledValue": { "type": "number" }, "actualCost": { "type": "number" }, "disbursementCost": { "type": "number" }, "unbilledDisbursements": { "type": "number" }, "billingType": { "type": "string" }, "fixedFee": { "type": "number" }, "margin": { "type": "number" }, "budgetUsedPercent": { "type": "number" }, "ownerUserId": { "type": "string" }, "memberUserIds": { "type": "array", "items": { "type": "object" } }, "anyoneCanLogTime": { "type": "boolean" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hourlyRate": 15.0, "billable": true, "active": true, "budgetHours": 3.0, "budgetAmount": 10005.0, "actualHours": 3.0, "billableHours": 3.0, "actualValue": 10005.0, "unbilledValue": 10005.0, "actualCost": 10005.0, "disbursementCost": 10005.0, "unbilledDisbursements": 1.0, "billingType": "standard", "fixedFee": 1.0, "margin": 1.0, "budgetUsedPercent": 15.0, "ownerUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "memberUserIds": [], "anyoneCanLogTime": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/settings": { "get": { "tags": [ "Time tracking" ], "summary": "The time lock date and the hours a week each person is expected to log.", "operationId": "getApiTimeTrackingSettings", "description": "Requires the `time-tracking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiTimeTrackingSettingsRequest" }, "example": { "lockDate": "2026-09-01", "weeklyHours": 3.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Time tracking" ], "summary": "Move the time lock date (time on or before it cannot be added, corrected or removed) and set the hours a week. Needs approve.", "operationId": "putApiTimeTrackingSettings", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiTimeTrackingSettingsRequest" }, "example": { "lockDate": "2026-09-30", "weeklyHours": 40.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiTimeTrackingSettingsRequest" }, "example": { "lockDate": "2026-09-01", "weeklyHours": 3.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/reports/utilisation": { "get": { "tags": [ "Time tracking" ], "summary": "Utilisation per person for the period (at most a year): hours worked; approved billable and billed hours and the value of each at the rates recorded; available hours from the person's own hours a week, else the business's hours a week (weeklyHoursSource says which; with neither, availableHours and utilisation are null and availableReason says why); utilisation (approved billable ÷ available, in percent) and realisation — shown as the billed share — (billed value ÷ billable value, in percent; an invoice line reduced after it was raised is not reflected), with the unbilled value beside them; capacityHours and ofCapacity are kept for callers of the earlier shape. Needs timetracking:edit.", "operationId": "getApiTimeTrackingReportsUtilisation", "description": "Requires the `time-tracking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-10-31" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "dateFrom": { "type": "string", "format": "date" }, "dateTo": { "type": "string", "format": "date" }, "workingDays": { "type": "number" }, "companyWeeklyHours": { "type": "number" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "weeklyHours": { "type": "number" }, "weeklyHoursSource": { "type": "string" }, "availableHours": { "type": "number" }, "hours": { "type": "number" }, "billableHours": { "type": "number" }, "billedHours": { "type": "number" }, "billableValue": { "type": "number" }, "billedValue": { "type": "number" }, "unbilledValue": { "type": "number" }, "utilisation": { "type": "number" }, "realisation": { "type": "number" }, "capacityHours": { "type": "number" }, "ofCapacity": { "type": "number" } } } }, "totals": { "type": "object", "properties": { "name": { "type": "string" }, "weeklyHours": { "type": "number" }, "availableHours": { "type": "number" }, "hours": { "type": "number" }, "billableHours": { "type": "number" }, "billedHours": { "type": "number" }, "billableValue": { "type": "number" }, "billedValue": { "type": "number" }, "unbilledValue": { "type": "number" }, "utilisation": { "type": "number" }, "realisation": { "type": "number" }, "capacityHours": { "type": "number" }, "ofCapacity": { "type": "number" } } }, "hours": { "type": "number" }, "billableHours": { "type": "number" }, "utilisation": { "type": "number" } } }, "example": { "dateFrom": "2026-10-01", "dateTo": "2026-10-31", "workingDays": 22.0, "companyWeeklyHours": 40.0, "rows": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Thandi Mokoena", "weeklyHours": 40.0, "weeklyHoursSource": "person", "availableHours": 176.0, "hours": 150.0, "billableHours": 132.0, "billedHours": 100.0, "billableValue": 125400.0, "billedValue": 95000.0, "unbilledValue": 30400.0, "utilisation": 75.0, "realisation": 75.76, "capacityHours": 176.0, "ofCapacity": 85.23 } ], "totals": { "name": "Total", "weeklyHours": 40.0, "availableHours": 176.0, "hours": 150.0, "billableHours": 132.0, "billedHours": 100.0, "billableValue": 125400.0, "billedValue": 95000.0, "unbilledValue": 30400.0, "utilisation": 75.0, "realisation": 75.76, "capacityHours": 176.0, "ofCapacity": 85.23 }, "hours": 150.0, "billableHours": 132.0, "utilisation": 75.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/projects/{id}/milestones": { "get": { "tags": [ "Time tracking" ], "summary": "A fixed-fee project's milestones and the invoice each is on.", "operationId": "getApiTimeTrackingProjectsByIdMilestones", "description": "Requires the `time-tracking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiTimeTrackingProjectsByIdMilestonesResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiTimeTrackingProjectsByIdMilestonesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Time tracking" ], "summary": "Add a milestone to a fixed-fee project; the milestones never come to more than the fee.", "operationId": "postApiTimeTrackingProjectsByIdMilestones", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "amount": { "type": "number" }, "dueDate": { "type": "string", "format": "date" } } }, "example": { "name": "Design signed off", "amount": 40000.0, "dueDate": "2026-11-30" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiTimeTrackingProjectsByIdMilestonesResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiTimeTrackingProjectsByIdMilestonesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/projects/{id}/milestones/{milestoneId}/invoice": { "post": { "tags": [ "Time tracking" ], "summary": "Invoice a milestone (a draft, once); a voided invoice gives the milestone back.", "operationId": "postApiTimeTrackingProjectsByIdMilestonesByMilestoneIdInvoice", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "milestoneId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiTimeTrackingProjectsByIdMilestonesResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiTimeTrackingProjectsByIdMilestonesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/projects/{id}": { "put": { "tags": [ "Time tracking" ], "summary": "Update a project. Repricing changes future entries only — logged hours keep the rate they were logged at.", "operationId": "putApiTimeTrackingProjectsById", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "contactId": { "type": "string" }, "hourlyRate": { "type": "number" }, "billable": { "type": "boolean" }, "active": { "type": "boolean" }, "budgetHours": { "type": "number" }, "budgetAmount": { "type": "number" }, "billingType": { "type": "string" }, "fixedFee": { "type": "number" }, "clearBudgetHours": { "type": "boolean" }, "clearBudgetAmount": { "type": "boolean" }, "clearContactId": { "type": "boolean" }, "anyoneCanLogTime": { "type": "boolean" }, "memberUserIds": { "type": "array", "items": { "type": "object" } } } }, "example": { "name": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hourlyRate": 15.0, "billable": true, "active": true, "budgetHours": 3.0, "budgetAmount": 10005.0, "billingType": "standard", "fixedFee": 1.0, "clearBudgetHours": false, "clearBudgetAmount": false, "clearContactId": false, "anyoneCanLogTime": true, "memberUserIds": [] } } } }, "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/projects/{id}/invoice": { "post": { "tags": [ "Time tracking" ], "summary": "Invoice a project's approved, unbilled hours as service lines.", "operationId": "postApiTimeTrackingProjectsByIdInvoice", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issueDate": { "type": "string", "format": "date" }, "terms": { "type": "string" } } }, "example": { "issueDate": "2026-08-31", "terms": "30" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "entriesBilled": { "type": "integer" } } }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "entriesBilled": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/timer/active": { "get": { "tags": [ "Time tracking" ], "summary": "The running timer, if there is one.", "operationId": "getApiTimeTrackingTimerActive", "description": "Requires the `time-tracking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "timer": { "$ref": "#/components/schemas/PostApiTimeTrackingTimerStartResponse" } } }, "example": { "timer": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "projectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "projectName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "startedAtEpochMs": 1, "billable": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/timer/start": { "post": { "tags": [ "Time tracking" ], "summary": "Start a timer.", "operationId": "postApiTimeTrackingTimerStart", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "description": { "type": "string" }, "taskId": { "type": "string" } } }, "example": { "projectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "API work", "taskId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiTimeTrackingTimerStartResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "projectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "projectName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "startedAtEpochMs": 1, "billable": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/timer/{id}/stop": { "post": { "tags": [ "Time tracking" ], "summary": "Stop a timer and write the entry.", "operationId": "postApiTimeTrackingTimerByIdStop", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "stopped" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/weekly-totals": { "get": { "tags": [ "Time tracking" ], "summary": "The week's totals per person and per project.", "operationId": "getApiTimeTrackingWeeklyTotals", "description": "Requires the `time-tracking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "week", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-W34" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "weekStart": { "type": "string", "format": "date" }, "totalHours": { "type": "number" }, "billableHours": { "type": "number" }, "unbilledRevenue": { "type": "number" } } }, "example": { "weekStart": "2026-09-01", "totalHours": 3.0, "billableHours": 3.0, "unbilledRevenue": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/people": { "get": { "tags": [ "Time tracking" ], "summary": "Everybody's standing charge-out and cost rates — what an hour defaults to when no task rate or typed rate applies. Needs timetracking:edit, the read as well as the write: a cost rate is close to what somebody is paid. A rate that is not set is null, never zero.", "operationId": "getApiTimeTrackingPeople", "description": "Requires the `time-tracking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiTimeTrackingPeopleResponseItem" } }, "example": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Thandi Mokoena", "defaultChargeRate": 950.0, "defaultCostRate": 420.0, "weeklyHours": 40.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/people/{userId}/rates": { "put": { "tags": [ "Time tracking" ], "summary": "Set or clear a person's standing rates from Time Tracking. The same figures, and the same writer, as the job-card technician rates — two doors, one owner. A null leaves a figure alone; clearChargeRate / clearCostRate / clearWeeklyHours empty it. weeklyHours is the person's standing working week (more than 0, at most 100, the same bound as the business's hours a week), and it beats the business's, which the utilisation report spreads over the period's working days.", "operationId": "putApiTimeTrackingPeopleByUserIdRates", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultChargeRate": { "type": "number" }, "defaultCostRate": { "type": "number" }, "clearChargeRate": { "type": "boolean" }, "clearCostRate": { "type": "boolean" }, "weeklyHours": { "type": "number" }, "clearWeeklyHours": { "type": "boolean" } } }, "example": { "defaultChargeRate": 950.0, "defaultCostRate": 420.0, "clearChargeRate": false, "clearCostRate": false, "weeklyHours": 40.0, "clearWeeklyHours": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiTimeTrackingPeopleResponseItem" }, "example": { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Thandi Mokoena", "defaultChargeRate": 950.0, "defaultCostRate": 420.0, "weeklyHours": 40.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/projects/{id}/tasks": { "get": { "tags": [ "Time tracking" ], "summary": "Tasks on a project, with their charge and cost rates. `timetracking:view`.", "operationId": "getApiTimeTrackingProjectsByIdTasks", "description": "Requires the `time-tracking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiTimeTrackingProjectsByIdTasksResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "projectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "chargeRate": 15.0, "costRate": 15.0, "active": true, "sortOrder": 1, "effectiveRate": 15.0, "effectiveRateSource": "referral", "loggedHours": 3.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Time tracking" ], "summary": "Add a task to a project. `timetracking:create`. A rate left null is 'not set' rather than zero — a zero cost rate reports a 100% margin.", "operationId": "postApiTimeTrackingProjectsByIdTasks", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "chargeRate": { "type": "number" }, "costRate": { "type": "number" }, "active": { "type": "boolean" }, "sortOrder": { "type": "integer" } } }, "example": { "name": "Site survey", "chargeRate": 950.0, "costRate": 480.0, "active": true, "sortOrder": 0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiTimeTrackingProjectsByIdTasksResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "projectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "chargeRate": 15.0, "costRate": 15.0, "active": true, "sortOrder": 1, "effectiveRate": 15.0, "effectiveRateSource": "referral", "loggedHours": 3.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/time-tracking/projects/{id}/tasks/{taskId}": { "put": { "tags": [ "Time tracking" ], "summary": "Correct a task. `timetracking:edit`. Set clearChargeRate or clearCostRate to unset a rate: null cannot say 'unset'.", "operationId": "putApiTimeTrackingProjectsByIdTasksByTaskId", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "chargeRate": { "type": "number" }, "costRate": { "type": "number" }, "active": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "clearChargeRate": { "type": "boolean" }, "clearCostRate": { "type": "boolean" } } }, "example": { "name": "Site survey", "chargeRate": 950.0, "costRate": 480.0, "active": true, "sortOrder": 0, "clearChargeRate": false, "clearCostRate": false } } } }, "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Time tracking" ], "summary": "Remove a task. `timetracking:delete`.", "operationId": "deleteApiTimeTrackingProjectsByIdTasksByTaskId", "description": "Requires the `time-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "time-tracking:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "retired": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "retired": true, "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/templates": { "get": { "tags": [ "Workflows" ], "summary": "The five board templates the new-board dialog offers, each with its columns and the stage every column maps to. Data in `shared`, not rows: a template is read once at creation and the board owns its columns from that moment.", "operationId": "getApiWorkflowsTemplates", "description": "Requires the `workflows:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "blurb": { "type": "string" }, "suggestedPrefix": { "type": "string" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiWorkflowsBoardsResponseColumnsItem" } } } } } } }, "example": { "templates": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "blurb": "Budget deferred to the next financial year.", "suggestedPrefix": "INV-", "columns": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "stage": "text", "position": 1, "wipLimit": 50, "count": 3 } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/members": { "get": { "tags": [ "Workflows" ], "summary": "People a card can be assigned to. Four fields, not the user row — this fills a dropdown, and shipping roles, sessions and 2FA state to do that is the unbounded-list problem with a new name.", "operationId": "getApiWorkflowsMembers", "description": "Requires the `workflows:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } } } } }, "example": { "members": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/link-options": { "get": { "tags": [ "Workflows" ], "summary": "Matters, customers and (for a practice) clients a board or a card can be linked to, and the periods, bank reconciliations, invoices and bills a close card can close (closesKind period | reconciliation | invoice | bill, closesId the record), as {id, name} pairs. Each list is bounded; ?q= narrows every list in SQL, invoices and bills by number or customer/supplier. Served here rather than from /api/time-tracking/projects and /api/contacts for the reason /api/bom/products exists: a role holding only workflows:* cannot call either, so the picker would be empty for exactly the person whose screen it is. Hours logged on a card become time entries against the matter this names.", "operationId": "getApiWorkflowsLinkOptions", "description": "Requires the `workflows:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "clients": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "reconciliations": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "bills": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } } } }, "example": { "projects": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ], "contacts": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ], "clients": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ], "periods": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ], "reconciliations": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ], "invoices": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ], "bills": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/boards": { "get": { "tags": [ "Workflows" ], "summary": "Every board this company can see, with its columns and live counts. A board with no company is visible to all of them — the cost_centres shape. Archived boards are excluded unless asked for.", "operationId": "getApiWorkflowsBoards", "description": "Requires the `workflows:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "archived", "in": "query", "required": false, "description": "Include archived rows.", "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "boards": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiWorkflowsBoardsResponse" } } } }, "example": { "boards": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "keyPrefix": "INV-", "description": "Consulting services — August 2026", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectName": "Karoo Fresh Holdings Ltd", "archived": true, "columns": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "stage": "text", "position": 1, "wipLimit": 50, "count": 3 } ], "itemCount": 3, "openCount": 3, "createdAt": "2026-09-01T09:15:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Workflows" ], "summary": "Create a board from a template. The prefix is normalised upper case and must be free across the tenant, because it is half of every item number people quote to each other.", "operationId": "postApiWorkflowsBoards", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "keyPrefix": { "type": "string" }, "description": { "type": "string" }, "templateId": { "type": "string" }, "contactId": { "type": "string" }, "timeProjectId": { "type": "string" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiWorkflowsBoardsRequestColumnsItem" } } } }, "example": { "name": "Month-end close", "keyPrefix": "CLOSE", "description": "Reconciliations and reviews for one period", "templateId": "month-end", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "columns": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "stage": "todo", "wipLimit": 50, "gate": false } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkflowsBoardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiWorkflowsBoardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/boards/{id}": { "get": { "tags": [ "Workflows" ], "summary": "One board, with its columns and their live counts.", "operationId": "getApiWorkflowsBoardsById", "description": "Requires the `workflows:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkflowsBoardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiWorkflowsBoardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Workflows" ], "summary": "Rename, re-point or archive a board, and save its columns as a WHOLE list. Whole-list because reorder, rename, add and remove happen in one dialog — four endpoints would let a board be saved with a column deleted and its replacement not yet added. A column still holding cards is refused, never orphaned.", "operationId": "putApiWorkflowsBoardsById", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "contactId": { "type": "string" }, "timeProjectId": { "type": "string" }, "archived": { "type": "boolean" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiWorkflowsBoardsRequestColumnsItem" } } } }, "example": { "name": "Month-end close", "description": "Reconciliations and reviews", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "archived": false, "columns": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Not started", "stage": "todo", "wipLimit": 50, "gate": false }, { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "In progress", "stage": "in_progress", "wipLimit": 5, "gate": false } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkflowsBoardsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiWorkflowsBoardsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Workflows" ], "summary": "Delete an EMPTY board. One still holding cards is refused with the count and told to archive instead — deleting would strand their comments, their history and any hours logged against them.", "operationId": "deleteApiWorkflowsBoardsById", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/boards/{id}/items": { "get": { "tags": [ "Workflows" ], "summary": "The board's cards. `q` is the board's filter language — `is:` `stage:` `column:` `type:` `priority:` `label:` `assignee:` `for:` `due:` plus bare words, same key OR, different keys AND. Parsed by one object in `shared` so the client and the server cannot disagree about what `a:me` means.", "operationId": "getApiWorkflowsBoardsByIdItems", "description": "Requires the `workflows:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "is%3Aoverdue+p%3Aurgent" }, { "name": "offset", "in": "query", "required": false, "description": "How many rows to skip. Use with `limit` to page. A paged response reports `total`, which is the number of rows matching the filter rather than the number returned.", "schema": { "type": "integer" }, "example": "0" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiWorkflowsItemsResponse" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "boardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "columnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stage": "text", "columnName": "Karoo Fresh Holdings Ltd", "itemKey": "text", "title": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "itemType": "standard", "priority": "normal", "labels": [ "Karoo Fresh Holdings Ltd" ], "assigneeUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "assigneeName": "Thandi Mokoena", "reporterUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reporterName": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectName": "Karoo Fresh Holdings Ltd", "estimateMinutes": 1, "loggedMinutes": 1, "dueDate": "2026-09-01", "rank": 1.0, "startedAt": "2026-09-01T09:15:00Z", "closedAt": "2026-09-01T09:15:00Z", "commentCount": 3, "attachmentCount": 3, "recurrenceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "recurrenceName": "Karoo Fresh Holdings Ltd", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ], "total": 42, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/boards/{id}/insights": { "get": { "tags": [ "Workflows" ], "summary": "Flow. Work in progress against each column's limit, throughput per week, and cycle time as a MEDIAN plus the 85th percentile — a mean over one card that waited four months for a supplier reports a typical card as taking three weeks, which is true of nothing on the board.", "operationId": "getApiWorkflowsBoardsByIdInsights", "description": "Requires the `workflows:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "boardId": { "type": "string" }, "total": { "type": "integer" }, "open": { "type": "integer" }, "wip": { "type": "integer" }, "blocked": { "type": "integer" }, "overdue": { "type": "integer" }, "dueThisWeek": { "type": "integer" }, "unassigned": { "type": "integer" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkflowsBoardsByIdInsightsResponseColumnsItem" } }, "breaches": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkflowsBoardsByIdInsightsResponseColumnsItem" } }, "completedInWindow": { "type": "integer" }, "cancelledInWindow": { "type": "integer" }, "throughputPerWeek": { "type": "number" }, "medianCycleDays": { "type": "integer" }, "p85CycleDays": { "type": "integer" }, "medianQueueDays": { "type": "integer" }, "oldestOpenDays": { "type": "integer" }, "windowDays": { "type": "integer" }, "byAssignee": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "open": { "type": "integer" }, "overdue": { "type": "integer" } } } } } }, "example": { "boardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "total": 42, "open": 1, "wip": 1, "blocked": 1, "overdue": 1, "dueThisWeek": 1, "unassigned": 1, "columns": [ { "columnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "stage": "text", "count": 3, "limit": 50, "over": false } ], "breaches": [ { "columnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "stage": "text", "count": 3, "limit": 50, "over": false } ], "completedInWindow": 1, "cancelledInWindow": 1, "throughputPerWeek": 1.0, "medianCycleDays": 30, "p85CycleDays": 30, "medianQueueDays": 30, "oldestOpenDays": 30, "windowDays": 28, "byAssignee": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "open": 1, "overdue": 1 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/boards/{id}/export": { "get": { "tags": [ "Workflows" ], "summary": "The board as CSV. Gated on workflows:export.", "operationId": "getApiWorkflowsBoardsByIdExport", "description": "Requires the `workflows:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/items": { "post": { "tags": [ "Workflows" ], "summary": "Raise a card. The item number comes off the board's own counter taken FOR UPDATE, never count(*), which reissues a number the moment anything is deleted. A card inherits the board's matter unless it names its own.", "operationId": "postApiWorkflowsItems", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "boardId": { "type": "string" }, "clientTenantId": { "type": "string" }, "columnId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "itemType": { "type": "string" }, "priority": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "assigneeUserId": { "type": "string" }, "contactId": { "type": "string" }, "timeProjectId": { "type": "string" }, "estimateMinutes": { "type": "integer" }, "dueDate": { "type": "string", "format": "date" }, "closesKind": { "type": "string" }, "closesId": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "boardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "columnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "title": "Reconcile the FNB cheque account", "description": "Statement to 31 August", "itemType": "task", "priority": "high", "labels": [ "vat", "fnb" ], "assigneeUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "estimateMinutes": 120, "dueDate": "2026-09-07", "closesKind": "reconciliation", "closesId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkflowsItemsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiWorkflowsItemsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/items/{id}": { "get": { "tags": [ "Workflows" ], "summary": "One card with its comments, its history and the time logged against it. The history is read from `audit_log` rather than a second trail, so “who moved this card” has one answer. The individual time entries are included only for a caller holding timetracking:view.", "operationId": "getApiWorkflowsItemsById", "description": "Requires the `workflows:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "id": { "type": "string" }, "boardId": { "type": "string" }, "columnId": { "type": "string" }, "stage": { "type": "string" }, "columnName": { "type": "string" }, "itemKey": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "itemType": { "type": "string" }, "priority": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "assigneeUserId": { "type": "string" }, "assigneeName": { "type": "string" }, "reporterUserId": { "type": "string" }, "reporterName": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "timeProjectId": { "type": "string" }, "timeProjectName": { "type": "string" }, "clientTenantId": { "type": "string" }, "workOrderId": { "type": "string" }, "workOrderNumber": { "type": "string" }, "lotNumber": { "type": "string" }, "clientName": { "type": "string" }, "estimateMinutes": { "type": "integer" }, "loggedMinutes": { "type": "integer" }, "dueDate": { "type": "string", "format": "date" }, "rank": { "type": "number" }, "startedAt": { "type": "string" }, "closedAt": { "type": "string" }, "commentCount": { "type": "integer" }, "attachmentCount": { "type": "integer" }, "recurrenceId": { "type": "string" }, "recurrenceName": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/DeleteApiWorkflowsCommentsByIdResponse" } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string" }, "actorName": { "type": "string" }, "detail": { "type": "string" }, "createdAt": { "type": "string" } } } }, "timeEntries": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiWorkflowsItemsByIdTimeResponse" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkflowsItemsByIdResponseAttachmentsItem" } }, "checklist": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiWorkflowsChecklistByIdResponseItem" } } } }, "example": { "item": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "boardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "columnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stage": "text", "columnName": "Karoo Fresh Holdings Ltd", "itemKey": "text", "title": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "itemType": "standard", "priority": "normal", "labels": [ "Karoo Fresh Holdings Ltd" ], "assigneeUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "assigneeName": "Thandi Mokoena", "reporterUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reporterName": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectName": "Karoo Fresh Holdings Ltd", "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workOrderNumber": "PO-0001", "lotNumber": "INV-0001", "clientName": "Karoo Fresh Holdings Ltd", "estimateMinutes": 1, "loggedMinutes": 1, "dueDate": "2026-09-01", "rank": 1.0, "startedAt": "2026-09-01T09:15:00Z", "closedAt": "2026-09-01T09:15:00Z", "commentCount": 3, "attachmentCount": 3, "recurrenceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "recurrenceName": "Karoo Fresh Holdings Ltd", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" }, "comments": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "itemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "authorUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "authorName": "Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached.", "createdAt": "2026-09-01T09:15:00Z" } ], "activity": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "action": "created", "actorName": "Karoo Fresh Holdings Ltd", "detail": "Saved.", "createdAt": "2026-09-01T09:15:00Z" } ], "timeEntries": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userName": "Thandi Mokoena", "minutes": 1, "description": "Consulting services — August 2026", "entryDate": "2026-09-01", "billable": true, "approved": false } ], "attachments": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "filename": "SignedPO-4417.pdf", "caption": "Serial plate before fitting", "contentType": "application/pdf", "sizeBytes": 1, "url": "https://app.ledgrsa.com/pay/3f1a7c92", "uploadedByName": "Karoo Fresh Holdings Ltd", "createdAt": "2026-09-01T09:15:00Z" } ], "checklist": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "done": false, "doneAt": "2026-09-01T09:15:00Z", "doneByName": "Karoo Fresh Holdings Ltd" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Workflows" ], "summary": "Edit a card. Every field optional; null leaves it alone and “” clears it — the three-state convention bills.purchase_order_id established, so a caller learns one rule rather than two.", "operationId": "putApiWorkflowsItemsById", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "itemType": { "type": "string" }, "priority": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "assigneeUserId": { "type": "string" }, "contactId": { "type": "string" }, "timeProjectId": { "type": "string" }, "estimateMinutes": { "type": "integer" }, "dueDate": { "type": "string", "format": "date" }, "closesKind": { "type": "string" }, "closesId": { "type": "string" } } }, "example": { "title": "Reconcile the FNB cheque account", "description": "Statement to 31 August", "itemType": "task", "priority": "urgent", "labels": [ "vat" ], "assigneeUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "", "timeProjectId": "", "estimateMinutes": 180, "dueDate": "2026-09-07", "closesKind": "period", "closesId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkflowsItemsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiWorkflowsItemsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Workflows" ], "summary": "Soft-delete a card. Owner and Admin only by default.", "operationId": "deleteApiWorkflowsItemsById", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/items/{id}/move": { "post": { "tags": [ "Workflows" ], "summary": "A drag. `insertIndex` rather than a rank: the client knows where the card landed between its neighbours and the server owns what number that becomes, so the fractional-index arithmetic — including renumbering an exhausted gap — lives on one side of the wire. A column at its work-in-progress limit refuses with a 409 naming the count and the limit.", "operationId": "postApiWorkflowsItemsByIdMove", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "columnId": { "type": "string" }, "insertIndex": { "type": "integer" } } }, "example": { "columnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "insertIndex": 0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/PostApiWorkflowsItemsResponse" }, "warning": { "type": "string" }, "rebalanced": { "type": "boolean" } } }, "example": { "item": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "boardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "columnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stage": "text", "columnName": "Karoo Fresh Holdings Ltd", "itemKey": "text", "title": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "itemType": "standard", "priority": "normal", "labels": [ "Karoo Fresh Holdings Ltd" ], "assigneeUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "assigneeName": "Thandi Mokoena", "reporterUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reporterName": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "timeProjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "timeProjectName": "Karoo Fresh Holdings Ltd", "estimateMinutes": 1, "loggedMinutes": 1, "dueDate": "2026-09-01", "rank": 1.0, "startedAt": "2026-09-01T09:15:00Z", "closedAt": "2026-09-01T09:15:00Z", "commentCount": 3, "attachmentCount": 3, "recurrenceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "recurrenceName": "Karoo Fresh Holdings Ltd", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" }, "warning": "text", "rebalanced": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/items/{id}/checklist": { "post": { "tags": [ "Workflows" ], "summary": "Add a step to the checklist inside a card; answers the card's checklist.", "operationId": "postApiWorkflowsItemsByIdChecklist", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiInventoryAdjustmentReasonsRequest" }, "example": { "label": "Agree the output tax to the ledger" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiWorkflowsChecklistByIdResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "done": false, "doneAt": "2026-09-01T09:15:00Z", "doneByName": "Karoo Fresh Holdings Ltd" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/checklist/{id}": { "put": { "tags": [ "Workflows" ], "summary": "Tick or untick a checklist step (done), or rename it (label); answers the card's checklist.", "operationId": "putApiWorkflowsChecklistById", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "done": { "type": "boolean" }, "label": { "type": "string" } } }, "example": { "done": true, "label": "Agree the output tax to the ledger" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiWorkflowsChecklistByIdResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "done": false, "doneAt": "2026-09-01T09:15:00Z", "doneByName": "Karoo Fresh Holdings Ltd" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Workflows" ], "summary": "Remove a step from a card's checklist.", "operationId": "deleteApiWorkflowsChecklistById", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/items/{id}/comments": { "post": { "tags": [ "Workflows" ], "summary": "Comment on a card.", "operationId": "postApiWorkflowsItemsByIdComments", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "body": "Bank has sent the missing statement.", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiWorkflowsCommentsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/DeleteApiWorkflowsCommentsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/comments/{id}": { "delete": { "tags": [ "Workflows" ], "summary": "Soft-delete a comment.", "operationId": "deleteApiWorkflowsCommentsById", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiWorkflowsCommentsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/DeleteApiWorkflowsCommentsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/items/{id}/time": { "post": { "tags": [ "Workflows" ], "summary": "Log time against a card as a `time_entries` row. Gated on timetracking:create, NOT workflows:edit — the resource a permission names is the thing being written, never the screen it was written from. Refused when neither the card nor its board is linked to a project: time_entries.project_id is NOT NULL and picking one on the user's behalf would attribute somebody's afternoon to a client who never asked for it.", "operationId": "postApiWorkflowsItemsByIdTime", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "minutes": { "type": "integer" }, "description": { "type": "string" }, "entryDate": { "type": "string", "format": "date" }, "billable": { "type": "boolean" }, "clientId": { "type": "string" } } }, "example": { "minutes": 90, "description": "Cleared the September reconciling items", "entryDate": "2026-09-02", "billable": true, "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkflowsItemsByIdTimeResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userName": "Thandi Mokoena", "minutes": 1, "description": "Consulting services — August 2026", "entryDate": "2026-09-01", "billable": true, "approved": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/items/{id}/attachments": { "get": { "tags": [ "Workflows" ], "summary": "The files filed against one card, each with a signed URL minted for this read and never stored. A file that cannot be signed comes back with a null URL rather than being hidden — one unsignable file must not make the other four disappear.", "operationId": "getApiWorkflowsItemsByIdAttachments", "description": "Requires the `workflows:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBomByBomIdAttachmentsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomByBomIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Workflows" ], "summary": "Attach a file to a card. Raw BYTES with the name on the query string, not multipart and not base64 — base64 inflates a 4 MB scan by a third on exactly the connection this product is designed for. The declared content type is a hint used only to accept or refuse; what is stored comes from the closed list in `AttachableFile`. Twelve files a card, 15 MB each. Gated on `workflows:edit`, not `create`: the file nearly always goes onto a card that already exists.", "operationId": "postApiWorkflowsItemsByIdAttachments", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "filename", "in": "query", "required": false, "description": "The name to give the downloaded file.", "schema": { "type": "string" }, "example": "brief.pdf" }, { "name": "caption", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Serial%20plate%20before%20fitting" }, { "name": "contentType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "application%2Fpdf" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBomByBomIdAttachmentsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomByBomIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/items/{id}/attachments/{linkId}": { "delete": { "tags": [ "Workflows" ], "summary": "Unlink a file. Removes the LINK, never the bytes — the same attachment may be referenced from an expense or a sales document, and a board is not a place from which somebody should be able to destroy a receipt the books depend on. Deleting the file itself is DELETE /api/files/{id}.", "operationId": "deleteApiWorkflowsItemsByIdAttachmentsByLinkId", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBomByBomIdAttachmentsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomByBomIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/recurrences": { "get": { "tags": [ "Workflows" ], "summary": "Recurring checklists — the work that comes round again. Each carries its cadence, its next due date in words (never blank: \"Paused\" and \"Finished\" are answers) and the cards it raises.", "operationId": "getApiWorkflowsRecurrences", "description": "Requires the `workflows:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "boardId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "recurrences": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiWorkflowsRecurrencesResponse" } } } }, "example": { "recurrences": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "boardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "boardName": "Karoo Fresh Holdings Ltd", "name": "Karoo Fresh Holdings Ltd", "cadence": "text", "cadenceLabel": "Karoo Fresh Holdings Ltd", "anchorDate": "2026-09-01", "endsOn": "2026-09-01", "active": true, "columnId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "columnName": "Karoo Fresh Holdings Ltd", "lastRaisedOn": "2026-09-01", "nextDueLabel": "Karoo Fresh Holdings Ltd", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "title": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "itemType": "standard", "priority": "normal", "labels": [ "Karoo Fresh Holdings Ltd" ], "assigneeUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "assigneeName": "Thandi Mokoena", "estimateMinutes": 1, "dueOffsetDays": 30, "position": 1 } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Workflows" ], "summary": "Set up a checklist that raises itself. A month-end close is fourteen cards, not one, so the recurrence owns a LIST; each occurrence raises them as ordinary cards with nothing special about them afterwards. The cadence arithmetic is `MaintenanceSchedule`, shared with service contracts rather than copied, so a 31st anchor gives 31 Jan then 28 Feb then 31 Mar.", "operationId": "postApiWorkflowsRecurrences", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkflowsRecurrencesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiWorkflowsRecurrencesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/recurrences/{id}": { "get": { "tags": [ "Workflows" ], "summary": "One recurring checklist with its cards, in the shape the editor saves — a dialog that saves what it loaded has to load what it saves.", "operationId": "getApiWorkflowsRecurrencesById", "description": "Requires the `workflows:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkflowsRecurrencesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiWorkflowsRecurrencesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Workflows" ], "summary": "Edit a checklist. A line that keeps its id keeps its identity, and that is load-bearing: the idempotency key is (line, occurrence), so a line re-created with a fresh id would raise its card again for an occurrence already dealt with.", "operationId": "putApiWorkflowsRecurrencesById", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkflowsRecurrencesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiWorkflowsRecurrencesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Workflows" ], "summary": "Stop a checklist recurring. The cards it has already raised STAY — they are ordinary work somebody may be halfway through. Pausing is the reversible option and the list says so.", "operationId": "deleteApiWorkflowsRecurrencesById", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "cardsLeftStanding": { "type": "integer" } } }, "example": { "cardsLeftStanding": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/recurrences/{id}/raise": { "post": { "tags": [ "Workflows" ], "summary": "Raise everything this checklist owes, now — the same implementation the `workflow-recurrences` job runs, because a button with its own version would eventually raise a different set from the timer. Reports occurrences raised AND occurrences passed over as older than the backfill window: a run that reported only what it did would be indistinguishable from one that found nothing owed.", "operationId": "postApiWorkflowsRecurrencesByIdRaise", "description": "Requires the `workflows:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "workflows:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "raised": { "type": "integer" }, "cards": { "type": "integer" }, "occurrences": { "type": "array", "items": { "type": "string" } }, "skipped": { "type": "array", "items": { "type": "string" } }, "alreadyRaised": { "type": "integer" }, "note": { "type": "string" } } }, "example": { "raised": 1, "cards": 1, "occurrences": [ "text" ], "skipped": [ "text" ], "alreadyRaised": 1, "note": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/items": { "get": { "tags": [ "Rental & hire" ], "summary": "The hire register for the active company: every item and pool by name, with where its units are today.", "operationId": "getApiRentalItems", "description": "Requires the `rental:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRentalItemsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fixedAssetId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "assetNumber": "INV-0001", "name": "Karoo Fresh Holdings Ltd", "itemClass": "text", "kind": "standard", "quantity": 3, "available": 1, "reserved": 1, "onHire": 1, "inService": 1, "lost": 1, "status": "sent" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Rental & hire" ], "summary": "Register a fixed asset for hire, as one item (serial) or a pool of identical units. An asset is registered once; a disposed asset is refused.", "operationId": "postApiRentalItems", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fixedAssetId": { "type": "string" }, "kind": { "type": "string" }, "quantity": { "type": "integer" }, "itemClass": { "type": "string" }, "name": { "type": "string" }, "meterUnit": { "type": "string" }, "meterReading": { "type": "number" }, "serviceEvery": { "type": "number" }, "serviceEveryDays": { "type": "integer" }, "replacementValue": { "type": "number" } } }, "example": { "fixedAssetId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "pool", "quantity": 120, "itemClass": "Scaffolding", "name": "Plate compactor", "meterUnit": "hours", "meterReading": 210.0, "serviceEvery": 250.0, "serviceEveryDays": 180, "replacementValue": 18500.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRentalItemsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRentalItemsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/items/{id}": { "get": { "tags": [ "Rental & hire" ], "summary": "One item on the hire register.", "operationId": "getApiRentalItemsById", "description": "Requires the `rental:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRentalItemsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRentalItemsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "tags": [ "Rental & hire" ], "summary": "Rename, re-class or resize an item. A pool cannot shrink below the units booked, out, in service or lost; the counts themselves are not editable here.", "operationId": "patchApiRentalItemsById", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "integer" }, "itemClass": { "type": "string" }, "replacementValue": { "type": "number" }, "meterUnit": { "type": "string" }, "meterReading": { "type": "number" }, "serviceEvery": { "type": "number" }, "serviceEveryDays": { "type": "integer" } } }, "example": { "name": "Scaffold frame 2 m", "quantity": 140, "itemClass": "Compaction", "replacementValue": 18000.0, "meterUnit": "hours", "meterReading": 210.0, "serviceEvery": 250.0, "serviceEveryDays": 180 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRentalItemsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRentalItemsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Rental & hire" ], "summary": "Take an item off the register. Refused while any unit is booked, out, in service or lost.", "operationId": "deleteApiRentalItemsById", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/assets": { "get": { "tags": [ "Rental & hire" ], "summary": "Fixed assets of the active company that could go on the register: in use and not on it yet. Needs rental:create, not the ledger's own permission.", "operationId": "getApiRentalAssets", "description": "Requires the `rental:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "assetNumber": { "type": "string" }, "name": { "type": "string" }, "assetClassLabel": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "assetNumber": "INV-0001", "name": "Karoo Fresh Holdings Ltd", "assetClassLabel": "Karoo Fresh Holdings Ltd" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/utilisation": { "get": { "tags": [ "Rental & hire" ], "summary": "What each item works and earns over a window (default the last 30 days): unit-days on hire over unit-days owned, its share of what its hire documents posted, its depreciation and its service cost, by item and by class. Idle items are flagged.", "operationId": "getApiRentalUtilisation", "description": "Requires the `rental:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-14" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-13" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "items": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string" }, "name": { "type": "string" }, "itemClass": { "type": "string" }, "assetNumber": { "type": "string" }, "quantity": { "type": "integer" }, "daysOwned": { "type": "integer" }, "unitDaysOwned": { "type": "integer" }, "unitDaysOnHire": { "type": "integer" }, "utilisation": { "type": "number" }, "income": { "type": "number" }, "depreciation": { "type": "number" }, "serviceCost": { "type": "number" }, "net": { "type": "number" }, "idle": { "type": "boolean" } } } }, "classes": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiRentalUtilisationResponseTotals" } }, "totals": { "$ref": "#/components/schemas/GetApiRentalUtilisationResponseTotals" } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "items": [ { "itemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "itemClass": "text", "assetNumber": "INV-0001", "quantity": 1, "daysOwned": 30, "unitDaysOwned": 30, "unitDaysOnHire": 30, "utilisation": 1.0, "income": 1.0, "depreciation": 1.0, "serviceCost": 10005.0, "net": 8700.0, "idle": true } ], "classes": [ { "itemClass": "text", "items": 1, "unitDaysOwned": 30, "unitDaysOnHire": 30, "utilisation": 1.0, "income": 1.0, "depreciation": 1.0, "serviceCost": 10005.0, "net": 8700.0 } ], "totals": { "itemClass": "text", "items": 1, "unitDaysOwned": 30, "unitDaysOnHire": 30, "utilisation": 1.0, "income": 1.0, "depreciation": 1.0, "serviceCost": 10005.0, "net": 8700.0 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/items/{id}/sell": { "post": { "tags": [ "Rental & hire" ], "summary": "Sell an ex-hire item, or some of a pool, from the yard: an invoice issued to the buyer at the sale, coded to Profit on Disposal, and the units' share of the fixed asset disposed of against the price, so the sale is one net gain or loss. The invoice cannot then be voided or deleted; a credit note is the way back. Never stock: 1310 is not touched. Refused while the units are booked, out or away. Needs rental:edit and invoices:create.", "operationId": "postApiRentalItemsByIdSell", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "price": { "type": "number" }, "units": { "type": "integer" }, "on": { "type": "string", "format": "date" } } }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "price": 12000.0, "units": 1, "on": "2026-10-13" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "bookValue": { "type": "number" }, "price": { "type": "number" } } }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "bookValue": 10005.0, "price": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/settings": { "get": { "tags": [ "Rental & hire" ], "summary": "Which days of a hire the company charges: calendar, mon_fri or mon_sat (public holidays out on working days).", "operationId": "getApiRentalSettings", "description": "Requires the `rental:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiRentalSettingsRequest" }, "example": { "chargeableDays": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Rental & hire" ], "summary": "Set the chargeable-days rule. Needs rental:edit.", "operationId": "putApiRentalSettings", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiRentalSettingsRequest" }, "example": { "chargeableDays": "mon_fri" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiRentalSettingsRequest" }, "example": { "chargeableDays": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/rate-cards": { "get": { "tags": [ "Rental & hire" ], "summary": "Every rate card of the active company — per item, or per class of items. An item's own card wins over its class's.", "operationId": "getApiRentalRateCards", "description": "Requires the `rental:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiRentalRateCardsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hireItemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "itemClass": "text", "day": 1.0, "week": 1.0, "fourWeek": 1.0, "weekend": 1.0, "minimumDays": 1 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Rental & hire" ], "summary": "Create or replace the card for one item (hireItemId) or one class (itemClass) — exactly one. Rands per unit; week, four-week and weekend rates are optional.", "operationId": "putApiRentalRateCards", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hireItemId": { "type": "string" }, "day": { "type": "number" }, "week": { "type": "number" }, "minimumDays": { "type": "integer" }, "itemClass": { "type": "string" }, "fourWeek": { "type": "number" }, "weekend": { "type": "number" }, "meterAllowancePerDay": { "type": "number" }, "meterOverRate": { "type": "number" } } }, "example": { "hireItemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "day": 450.0, "week": 1350.0, "minimumDays": 1, "itemClass": "Compaction", "fourWeek": 3600.0, "weekend": 700.0, "meterAllowancePerDay": 8.0, "meterOverRate": 150.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiRentalRateCardsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hireItemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "itemClass": "text", "day": 1.0, "week": 1.0, "fourWeek": 1.0, "weekend": 1.0, "minimumDays": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/rate-cards/{id}": { "delete": { "tags": [ "Rental & hire" ], "summary": "Remove a rate card.", "operationId": "deleteApiRentalRateCardsById", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/quote": { "post": { "tags": [ "Rental & hire" ], "summary": "Price a hire: the cheapest mix of four-week periods, weeks and days covering the chargeable days, per line, ex VAT. Writes nothing. An item with no card is refused by name.", "operationId": "postApiRentalQuote", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "out": { "type": "string", "format": "date" }, "offHire": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRentalQuoteRequestLinesItem" } } } }, "example": { "out": "2026-10-05", "offHire": "2026-10-13", "lines": [ { "hireItemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 1 } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "out": { "type": "string" }, "offHire": { "type": "string" }, "chargeableDays": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "hireItemId": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "chargeableDays": { "type": "integer" }, "periods": { "type": "string" }, "perUnit": { "type": "number" }, "total": { "type": "number" } } } }, "total": { "type": "number" } } }, "example": { "out": "text", "offHire": "text", "chargeableDays": "text", "lines": [ { "hireItemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "quantity": 3, "chargeableDays": 30, "periods": "2026-09", "perUnit": 1.0, "total": 10005.0 } ], "total": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/items/{id}/availability": { "get": { "tags": [ "Rental & hire" ], "summary": "How many of an item are free on every day of from..to (the peak of the bookings on any one day), and the bookings around it.", "operationId": "getApiRentalItemsByIdAvailability", "description": "Requires the `rental:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-05" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-13" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "hireItemId": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "quantity": { "type": "integer" }, "free": { "type": "integer" }, "bookings": { "type": "array", "items": { "type": "object", "properties": { "contractNumber": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "quantity": { "type": "integer" } } } } } }, "example": { "hireItemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "from": "2026-09-01", "to": "2026-09-30", "quantity": 3, "free": 1, "bookings": [ { "contractNumber": "INV-0001", "from": "2026-09-01", "to": "2026-09-30", "quantity": 3 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts": { "get": { "tags": [ "Rental & hire" ], "summary": "The company's hire contracts, newest first, at most 200; ?status=booked|out|off_hired|returned|cancelled narrows it.", "operationId": "getApiRentalContracts", "description": "Requires the `rental:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "out" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiRentalContractsByIdResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contractNumber": "INV-0001", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "site": "text", "status": "sent", "outDate": "2026-09-01", "dueBack": "text", "offHiredOn": "2026-09-01", "offHireRequestedBy": "text", "offHireRequestedAt": "2026-09-01T09:15:00Z", "delivery": false, "collection": false, "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hireItemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "kind": "standard", "quantity": 3, "qtyOut": 3, "qtyBack": 3, "qtyMissing": 3, "withCustomer": 1, "toGo": 1, "offHiredOn": "2026-09-01", "hireCharge": 1.0, "periods": "2026-09", "meterUnit": "each", "meterOut": 1.0, "crossHired": false, "supplierName": "Karoo Fresh Holdings Ltd" } ], "charges": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "standard", "description": "Consulting services — August 2026", "quantity": 1, "unitAmount": 10005.0, "total": 10005.0 } ], "stops": [ { "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "stopType": "standard", "status": "sent", "hasProof": false } ], "photoCount": 3, "depositHeld": 1.0, "total": 10005.0, "billing": "text", "invoices": [ { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "kind": "invoice", "from": "2026-09-01", "to": "2026-09-30", "status": "sent", "total": 10005.0, "amountDue": 10005.0 } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Rental & hire" ], "summary": "Book a hire. The units are reserved for outDate..dueBack; a booking that would double-book an item or overdraw a pool answers 409 naming the contract in the way.", "operationId": "postApiRentalContracts", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "outDate": { "type": "string", "format": "date" }, "dueBack": { "type": "string", "format": "date" }, "site": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiRentalQuoteRequestLinesItem" } }, "delivery": { "type": "boolean" }, "collection": { "type": "boolean" }, "notes": { "type": "string" }, "billing": { "type": "string" } } }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "outDate": "2026-10-05", "dueBack": "2026-10-13", "site": "Erf 112, Midrand", "lines": [ { "hireItemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 40 } ], "delivery": true, "collection": true, "notes": "Gate code 4411", "billing": "on_return" } } } }, "responses": { "201": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}": { "get": { "tags": [ "Rental & hire" ], "summary": "One contract: its lines (booked, out, back, missing, with the customer), the hire charge so far from HireCharge, inspection charges and logistics stops.", "operationId": "getApiRentalContractsById", "description": "Requires the `rental:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiRentalContractsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiRentalContractsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "tags": [ "Rental & hire" ], "summary": "Change the site, notes or due date. A later due date is checked against the calendar like a booking.", "operationId": "patchApiRentalContractsById", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dueBack": { "type": "string", "format": "date" }, "site": { "type": "string" }, "notes": { "type": "string" }, "billing": { "type": "string" } } }, "example": { "dueBack": "2026-10-20", "site": "12 Main Road, Germiston", "notes": "Gate code 4411", "billing": "monthly_arrears" } } } }, "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Rental & hire" ], "summary": "Delete a booking nothing has gone out on and that holds no deposit.", "operationId": "deleteApiRentalContractsById", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}/dispatch": { "post": { "tags": [ "Rental & hire" ], "summary": "Send units out on a date — every unit still to go, or the lines named. Booked units move to on hire.", "operationId": "postApiRentalContractsByIdDispatch", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "on": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string" }, "quantity": { "type": "integer" } } } } } }, "example": { "on": "2026-10-05", "lines": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 1 } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRentalContractsByIdReturnResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRentalContractsByIdReturnResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}/off-hire": { "post": { "tags": [ "Rental & hire" ], "summary": "Off-hire on a date: the charge stops that day, whatever day it is collected. Units never sent are released.", "operationId": "postApiRentalContractsByIdOffHire", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "on": { "type": "string", "format": "date" }, "lineIds": { "type": "array", "items": { "type": "string" } } } }, "example": { "on": "2026-10-13", "lineIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRentalContractsByIdReturnResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRentalContractsByIdReturnResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}/return": { "post": { "tags": [ "Rental & hire" ], "summary": "The return inspection: per line, units back and missing, and cleaning and damage charges. A missing unit is charged at the item's replacement value. More than is with the customer is refused.", "operationId": "postApiRentalContractsByIdReturn", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "on": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string" }, "back": { "type": "integer" }, "missing": { "type": "integer" }, "cleaning": { "type": "number" } } } } } }, "example": { "on": "2026-10-15", "lines": [ { "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "back": 38, "missing": 2, "cleaning": 350.0 } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRentalContractsByIdReturnResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiRentalContractsByIdReturnResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}/cancel": { "post": { "tags": [ "Rental & hire" ], "summary": "Cancel a booking nothing has gone out on; its units are released.", "operationId": "postApiRentalContractsByIdCancel", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}/invoice": { "post": { "tags": [ "Rental & hire" ], "summary": "Invoice what is left of an off-hired hire: the days no invoice has charged and the inspection's charges, or a credit note for days a month billed in advance did not use. Needs invoices:create too.", "operationId": "postApiRentalContractsByIdInvoice", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}/cross-hire": { "post": { "tags": [ "Rental & hire" ], "summary": "Hire units in from another hire company to fill the booking: charged to the customer at the item's own rates, never on the register's counts. Off-hiring the line off-hires the supplier the same day and raises the supplier's bill.", "operationId": "postApiRentalContractsByIdCrossHire", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hireItemId": { "type": "string" }, "quantity": { "type": "integer" }, "supplierId": { "type": "string" }, "supplierDay": { "type": "number" }, "supplierWeek": { "type": "number" }, "supplierReference": { "type": "string" } } }, "example": { "hireItemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 1, "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierDay": 300.0, "supplierWeek": 900.0, "supplierReference": "GPH-7781" } } } }, "responses": { "201": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/cross-hires": { "get": { "tags": [ "Rental & hire" ], "summary": "Every cross-hire with the customer's charge beside the supplier's bill (as it posted to Hire-in Costs) and the margin.", "operationId": "getApiRentalCrossHires", "description": "Requires the `rental:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "contractId": { "type": "string" }, "contractNumber": { "type": "string" }, "lineId": { "type": "string" }, "itemName": { "type": "string" }, "quantity": { "type": "integer" }, "supplierName": { "type": "string" }, "customerName": { "type": "string" }, "offHiredOn": { "type": "string", "format": "date" }, "customerCharge": { "type": "number" }, "supplierCost": { "type": "number" }, "billId": { "type": "string" }, "margin": { "type": "number" } } } }, "example": [ { "contractId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contractNumber": "INV-0001", "lineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "itemName": "Karoo Fresh Holdings Ltd", "quantity": 3, "supplierName": "Karoo Fresh Holdings Ltd", "customerName": "Karoo Fresh Holdings Ltd", "offHiredOn": "2026-09-01", "customerCharge": 1.0, "supplierCost": 10005.0, "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "margin": 1.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}/photos": { "post": { "tags": [ "Rental & hire" ], "summary": "A photograph from the return inspection, as raw image bytes; recompressed by the server. ?movementId= ties it to a return.", "operationId": "postApiRentalContractsByIdPhotos", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "movementId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "caption", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Dent%20on%20the%20base%20plate" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiRentalContractsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiRentalContractsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}/deposit": { "get": { "tags": [ "Rental & hire" ], "summary": "The contract's deposit: what is held (taken less applied less refunded), every movement, and its pay links.", "operationId": "getApiRentalContractsByIdDeposit", "description": "Requires the `rental:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiRentalContractsByIdDepositResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiRentalContractsByIdDepositResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Rental & hire" ], "summary": "Take a refundable deposit at the counter into a bank account: DR bank / CR 2156, no VAT.", "operationId": "postApiRentalContractsByIdDeposit", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" }, "bankAccountId": { "type": "string" }, "on": { "type": "string", "format": "date" }, "method": { "type": "string" }, "reference": { "type": "string" } } }, "example": { "amount": 5000.0, "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "on": "2026-10-05", "method": "card", "reference": "Card slip 0042" } } } }, "responses": { "201": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}/deposit/link": { "post": { "tags": [ "Rental & hire" ], "summary": "Ask the hirer to pay the deposit online through the business's own Yoco or PayFast account; returns the page they open.", "operationId": "postApiRentalContractsByIdDepositLink", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gateway": { "type": "string" }, "amount": { "type": "number" } } }, "example": { "gateway": "yoco", "amount": 5000.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRentalContractsByIdDepositLinkResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "url": "https://app.ledgrsa.com/pay/3f1a7c92", "gateway": "payfast", "amount": 10005.0, "status": "sent", "paidAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}/deposit/link/{linkId}/cancel": { "post": { "tags": [ "Rental & hire" ], "summary": "Withdraw an unpaid deposit link so it takes nothing.", "operationId": "postApiRentalContractsByIdDepositLinkByLinkIdCancel", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRentalContractsByIdDepositLinkResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "url": "https://app.ledgrsa.com/pay/3f1a7c92", "gateway": "payfast", "amount": 10005.0, "status": "sent", "paidAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}/deposit/apply": { "post": { "tags": [ "Rental & hire" ], "summary": "Apply what is held to the hirer's invoice as a payment, up to what it owes. Needs invoices:edit too.", "operationId": "postApiRentalContractsByIdDepositApply", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRecurringByIdLeaseDepositApplyRequest" }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "on": "2026-10-15" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiRentalContractsByIdDepositResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiRentalContractsByIdDepositResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rental/contracts/{id}/deposit/refund": { "post": { "tags": [ "Rental & hire" ], "summary": "Refund what is held, all of it or the amount named, from a bank account.", "operationId": "postApiRentalContractsByIdDepositRefund", "description": "Requires the `rental:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "rental:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiRecurringByIdLeaseDepositRefundRequest" }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "on": "2026-10-15", "amount": 500.0, "reference": "EFT refund" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiRentalContractsByIdDepositResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiRentalContractsByIdDepositResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/overview": { "get": { "tags": [ "Bills of materials" ], "summary": "The structural health of the BOM graph. Leads on what BLOCKS planning — parts flagged make-in-house with no recipe, and cycles — rather than on counts.", "operationId": "getApiBomOverview", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" }, { "name": "offset", "in": "query", "required": false, "description": "How many rows to skip. Use with `limit` to page. A paged response reports `total`, which is the number of rows matching the filter rather than the number returned.", "schema": { "type": "integer" }, "example": "0" }, { "name": "awaitingDecision", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "bomCount": { "type": "integer" }, "activeBomCount": { "type": "integer" }, "makeItemCount": { "type": "integer" }, "buyItemCount": { "type": "integer" }, "phantomItemCount": { "type": "integer" }, "unplannedItemCount": { "type": "integer" }, "maxLevel": { "type": "integer" }, "cycleCount": { "type": "integer" }, "missingBomCount": { "type": "integer" }, "boms": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "productSku": { "type": "string" }, "productName": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string" }, "isDefault": { "type": "boolean" }, "outputQty": { "type": "number" }, "lineCount": { "type": "integer" }, "lowLevelCode": { "type": "integer" }, "estimatedUnitCost": { "type": "number" }, "hasSubAssemblies": { "type": "boolean" } } } }, "bomTotal": { "type": "integer" }, "pendingCount": { "type": "integer" }, "cycles": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "missingBoms": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBomOverviewResponseMissingBomsItem" } } } }, "example": { "bomCount": 3, "activeBomCount": 3, "makeItemCount": 3, "buyItemCount": 3, "phantomItemCount": 3, "unplannedItemCount": 3, "maxLevel": 1, "cycleCount": 3, "missingBomCount": 3, "boms": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productSku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "name": "Karoo Fresh Holdings Ltd", "version": "1", "status": "sent", "isDefault": false, "outputQty": 3.0, "lineCount": 3, "lowLevelCode": 1, "estimatedUnitCost": 2900.0, "hasSubAssemblies": false } ], "bomTotal": 42, "pendingCount": 3, "cycles": [ [ "text" ] ], "missingBoms": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "qty": 3.0, "sourceType": "invoice", "onHand": 1.0, "shortfall": 1.0, "unitCost": 2900.0, "extendedCost": 10005.0, "leadTimeDays": 30, "supplierName": "Karoo Fresh Holdings Ltd" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{productId}/explode": { "get": { "tags": [ "Bills of materials" ], "summary": "Multi-level explosion for a quantity, level by level. `basis` chooses what each bought-in part is valued at (planning, catalogue, on-hand, standard) and each line reports the basis that actually priced it; `override=:`, repeated, is a session-only what-if that is never saved.", "operationId": "getApiBomByProductIdExplode", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "qty", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "100" }, { "name": "bomId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "wholeRuns", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" }, { "name": "basis", "in": "query", "required": false, "schema": { "type": "string" }, "example": "standard" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "bomId": { "type": "string" }, "qty": { "type": "number" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "componentProductId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "parentProductId": { "type": "string" }, "level": { "type": "integer" }, "qtyPerTopUnit": { "type": "number" }, "totalQty": { "type": "number" }, "sourceType": { "type": "string" }, "viaBomId": { "type": "string" }, "bomLineId": { "type": "string" }, "componentBomId": { "type": "string" }, "scrapPercent": { "type": "number" }, "leadTimeOffsetDays": { "type": "integer" }, "isPhantom": { "type": "boolean" }, "lowLevelCode": { "type": "integer" }, "leadTimeDays": { "type": "integer" }, "onHand": { "type": "number" }, "unitCost": { "type": "number" }, "extendedCost": { "type": "number" } } } }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBomOverviewResponseMissingBomsItem" } }, "maxDepth": { "type": "integer" }, "purchasedLineCount": { "type": "integer" }, "manufacturedLineCount": { "type": "integer" }, "missingBoms": { "type": "array", "items": { "type": "string" } }, "cycles": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "rollup": { "type": "object", "properties": { "productId": { "type": "string" }, "materialCost": { "type": "number" }, "labourCost": { "type": "number" }, "overheadCost": { "type": "number" }, "totalCost": { "type": "number" }, "unitCost": { "type": "number" }, "currentCostPrice": { "type": "number" }, "variance": { "type": "number" }, "missingBoms": { "type": "array", "items": { "type": "string" } } } } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qty": 3.0, "nodes": [ { "componentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "parentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "level": 1, "qtyPerTopUnit": 1.0, "totalQty": 3.0, "sourceType": "invoice", "viaBomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentBomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "scrapPercent": 15.0, "leadTimeOffsetDays": 30, "isPhantom": false, "lowLevelCode": 1, "leadTimeDays": 30, "onHand": 1.0, "unitCost": 2900.0, "extendedCost": 10005.0 } ], "requirements": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "qty": 3.0, "sourceType": "invoice", "onHand": 1.0, "shortfall": 1.0, "unitCost": 2900.0, "extendedCost": 10005.0, "leadTimeDays": 30, "supplierName": "Karoo Fresh Holdings Ltd" } ], "maxDepth": 1, "purchasedLineCount": 3, "manufacturedLineCount": 3, "missingBoms": [ "text" ], "cycles": [ [ "text" ] ], "rollup": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "materialCost": 10005.0, "labourCost": 10005.0, "overheadCost": 10005.0, "totalCost": 10005.0, "unitCost": 2900.0, "currentCostPrice": 10005.0, "variance": 1.0, "missingBoms": [ "text" ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{productId}/where-used": { "get": { "tags": [ "Bills of materials" ], "summary": "Every parent this part appears in, at any level.", "operationId": "getApiBomByProductIdWhereUsed", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "parents": { "type": "array", "items": { "type": "object", "properties": { "parentProductId": { "type": "string" }, "parentSku": { "type": "string" }, "parentName": { "type": "string" }, "bomId": { "type": "string" }, "bomLineId": { "type": "string" }, "bomName": { "type": "string" }, "qtyPer": { "type": "number" }, "scrapPercent": { "type": "number" }, "outputQty": { "type": "number" }, "lowLevelCode": { "type": "integer" } } } }, "ancestors": { "type": "array", "items": { "type": "object", "properties": { "parentProductId": { "type": "string" }, "parentSku": { "type": "string" }, "parentName": { "type": "string" }, "bomId": { "type": "string" }, "bomLineId": { "type": "string" }, "bomName": { "type": "string" }, "level": { "type": "integer" }, "qtyPer": { "type": "number" }, "scrapPercent": { "type": "number" }, "outputQty": { "type": "number" }, "lowLevelCode": { "type": "integer" }, "qtyPerAncestorUnit": { "type": "number" }, "via": { "type": "array", "items": { "type": "string" } }, "isTopLevel": { "type": "boolean" }, "truncated": { "type": "boolean" } } } }, "truncated": { "type": "boolean" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "parents": [ { "parentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "parentSku": "LEN-TP-14G4", "parentName": "Karoo Fresh Holdings Ltd", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomName": "Karoo Fresh Holdings Ltd", "qtyPer": 1.0, "scrapPercent": 15.0, "outputQty": 3.0, "lowLevelCode": 1 } ], "ancestors": [ { "parentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "parentSku": "LEN-TP-14G4", "parentName": "Karoo Fresh Holdings Ltd", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomName": "Karoo Fresh Holdings Ltd", "level": 1, "qtyPer": 1.0, "scrapPercent": 15.0, "outputQty": 3.0, "lowLevelCode": 1, "qtyPerAncestorUnit": 1.0, "via": [ "text" ], "isTopLevel": false, "truncated": false } ], "truncated": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/detail": { "get": { "tags": [ "Bills of materials" ], "summary": "`kind` says whether this is something you make or a pack you sell. One BOM with its lines, effectivity and scrap factors, and what else a run of it makes. `outputs` is a recipe's co-products and by-products and is empty for a recipe that makes one thing; each carries `allocatedUnitCost`, what it would come in at on a run of the recipe as it now stands — computed from the price list and the recipe's own costs, never stored, so it cannot go stale. `primaryUnitCost` is what the finished good itself comes in at once the run's cost has been divided, and `byProductCredit` is what the by-products take off the run before the co-products share what is left.", "operationId": "getApiBomByBomIdDetail", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "productSku": { "type": "string" }, "productName": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "outputQty": { "type": "number" }, "labourCost": { "type": "number" }, "overheadCost": { "type": "number" }, "status": { "type": "string" }, "isDefault": { "type": "boolean" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "componentProductId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "qtyPer": { "type": "number" }, "scrapPercent": { "type": "number" }, "effectiveQtyPer": { "type": "number" }, "sourceType": { "type": "string" }, "sourceOverride": { "type": "string" }, "leadTimeOffsetDays": { "type": "integer" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" }, "positionRef": { "type": "string" }, "unit": { "type": "string" }, "sortOrder": { "type": "integer" }, "notes": { "type": "string" }, "unitCost": { "type": "number" }, "extendedCost": { "type": "number" }, "hasSubBom": { "type": "boolean" } } } }, "lowLevelCode": { "type": "integer" }, "estimatedUnitCost": { "type": "number" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productSku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "name": "Karoo Fresh Holdings Ltd", "version": "1", "outputQty": 3.0, "labourCost": 10005.0, "overheadCost": 10005.0, "status": "sent", "isDefault": false, "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "qtyPer": 1.0, "scrapPercent": 15.0, "effectiveQtyPer": 1.0, "sourceType": "invoice", "sourceOverride": "text", "leadTimeOffsetDays": 30, "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "positionRef": "INV-0001", "unit": "each", "sortOrder": 1, "notes": "Budget deferred to the next financial year.", "unitCost": 2900.0, "extendedCost": 10005.0, "hasSubBom": false } ], "lowLevelCode": 1, "estimatedUnitCost": 2900.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/planning/buffer-suggestion": { "get": { "tags": [ "Bills of materials" ], "summary": "The safety stock and reorder point an item's sales swing and lead time call for, beside what it has: demand over the lead time from its monthly sales (invoices less credit notes), safety stock = z × the swing over the lead time at the service level (90, 95 or 98 %, default 95), both rounded up to how the item is counted. Give productId for one item, or abcClass for every item planned in that class. An item with under six months of sales or no lead time carries a blocker instead. Writes nothing.", "operationId": "getApiBomPlanningBufferSuggestion", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "serviceLevel", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "95" }, { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "abcClass", "in": "query", "required": false, "schema": { "type": "string" }, "example": "A" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBomPlanningBufferSuggestionResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomPlanningBufferSuggestionResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/planning/buffer-suggestion/apply": { "post": { "tags": [ "Bills of materials" ], "summary": "Set these items' safety stock to what their sales call for at the service level, worked out again on the server. Items with no suggestion are left as they are; returns the items changed. The reorder point (Inventory's low-stock alert) is not written.", "operationId": "postApiBomPlanningBufferSuggestionApply", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productIds": { "type": "array", "items": { "type": "string" } }, "serviceLevel": { "type": "integer" } } }, "example": { "productIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "serviceLevel": 95 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBomPlanningBufferSuggestionResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomPlanningBufferSuggestionResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/planning": { "get": { "tags": [ "Bills of materials" ], "summary": "Per-item planning parameters — make or buy, lead time, lot sizing, safety stock.", "operationId": "getApiBomPlanning", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string" }, "example": "make" }, { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiBomPlanningResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "sourceType": "invoice", "leadTimeDays": 30, "safetyStock": 1.0, "lotSizing": "text", "fixedOrderQty": 3.0, "minOrderQty": 3.0, "orderMultiple": 1.0, "maxOrderQty": 3.0, "maxStockLevel": 1.0, "periodsOfSupply": 1, "preferredSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "preferredSupplierName": "Karoo Fresh Holdings Ltd", "planningCost": 10005.0, "abcClass": "text", "mrpActive": true, "notes": "Budget deferred to the next financial year.", "lowLevelCode": 1, "configured": false, "onHand": 1.0, "hasBom": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Bills of materials" ], "summary": "Set planning parameters for a product.", "operationId": "putApiBomPlanning", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "sourceType": { "type": "string" }, "leadTimeDays": { "type": "integer" }, "safetyStock": { "type": "number" }, "lotSizing": { "type": "string" }, "fixedOrderQty": { "type": "number" }, "minOrderQty": { "type": "number" }, "orderMultiple": { "type": "number" }, "maxOrderQty": { "type": "number" }, "maxStockLevel": { "type": "number" }, "periodsOfSupply": { "type": "integer" }, "preferredSupplierId": { "type": "string" }, "planningCost": { "type": "number" }, "abcClass": { "type": "string" }, "mrpActive": { "type": "boolean" }, "notes": { "type": "string" }, "reorderPoint": { "type": "number" }, "leadTimeBasis": { "type": "string" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceType": "make", "leadTimeDays": 5, "safetyStock": 20.0, "lotSizing": "lot_for_lot", "fixedOrderQty": 3.0, "minOrderQty": 3.0, "orderMultiple": 1.0, "maxOrderQty": 3.0, "maxStockLevel": 1.0, "periodsOfSupply": 1, "preferredSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "planningCost": 10005.0, "abcClass": "A", "mrpActive": true, "notes": "Budget deferred to the next financial year.", "reorderPoint": 1.0, "leadTimeBasis": "working" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiBomPlanningResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "sourceType": "invoice", "leadTimeDays": 30, "safetyStock": 1.0, "lotSizing": "text", "fixedOrderQty": 3.0, "minOrderQty": 3.0, "orderMultiple": 1.0, "maxOrderQty": 3.0, "maxStockLevel": 1.0, "periodsOfSupply": 1, "preferredSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "preferredSupplierName": "Karoo Fresh Holdings Ltd", "planningCost": 10005.0, "abcClass": "text", "mrpActive": true, "notes": "Budget deferred to the next financial year.", "lowLevelCode": 1, "configured": true, "onHand": 1.0, "hasBom": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/planning": { "put": { "tags": [ "Bills of materials" ], "summary": "Set planning parameters that belong to one BOM rather than the item.", "operationId": "putApiBomByBomIdPlanning", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isDefault": { "type": "boolean" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" } } }, "example": { "isDefault": true, "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "updated" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/lines/{lineId}/planning": { "put": { "tags": [ "Bills of materials" ], "summary": "Set a line's scrap factor and effectivity dates.", "operationId": "putApiBomLinesByLineIdPlanning", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceOverride": { "type": "string" }, "leadTimeOffsetDays": { "type": "integer" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" }, "positionRef": { "type": "string" }, "unit": { "type": "string" }, "operationSeq": { "type": "integer" } } }, "example": { "sourceOverride": "make", "leadTimeOffsetDays": 30, "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "positionRef": "INV-0001", "unit": "each", "operationSeq": 1 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "updated" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/planning/bulk-source": { "post": { "tags": [ "Bills of materials" ], "summary": "Flag many items make or buy at once.", "operationId": "postApiBomPlanningBulkSource", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productIds": { "type": "string" }, "sourceType": { "type": "string" } } }, "example": { "productIds": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03,8c2d4e61-0a7f-4b93-b5e2-71d9c3a8f420", "sourceType": "buy" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "count": { "type": "integer" } } }, "example": { "status": "updated", "count": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/products/{productId}/variants": { "get": { "tags": [ "Bills of materials" ], "summary": "A product's variants, for the recipe editor's variant pickers. Under bom:view for the same reason /api/bom/products exists: a role holding only `bom:*` cannot call Inventory, and a picker that 403s looks exactly like a product with no variants. An empty list is the answer for a product that does not come in variants, and the editor draws no chooser for it.", "operationId": "getApiBomProductsByProductIdVariants", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "CHR-DIN-OAK", "name": "Oak" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/products": { "get": { "tags": [ "Bills of materials" ], "summary": "The products this tenant can name in a recipe — id, SKU, name and whether stock is tracked. Exists because a role holding only `bom:*` cannot call /api/inventory/products, so without it the recipe editor has no way to name a finished good or a component.", "operationId": "getApiBomProducts", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBomProductsResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "isTracked": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}": { "get": { "tags": [ "Bills of materials" ], "summary": "One recipe in the shape the EDITOR saves — every field plus the component lines. Distinct from {bomId}/detail, which is the analysis shape (roll-up, tree, where-used): a dialog that saves what it loaded has to load what it saves.", "operationId": "getApiBomByBomId", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBomResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Bills of materials" ], "summary": "Edit a recipe. An empty `lines` list leaves the components alone; send a list to replace them. The finished good is NOT re-pointable — moving a recipe to another product would restate every build already costed against it.", "operationId": "putApiBomByBomId", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBomRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBomResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Bills of materials" ], "summary": "Remove a recipe — or ARCHIVE it when it has been built from, because it is then the record of how those units were costed. Gated on `bom:delete`.", "operationId": "deleteApiBomByBomId", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom": { "post": { "tags": [ "Bills of materials" ], "summary": "Author a recipe. Gated on `bom:create`, over the same implementation /api/inventory/boms uses — so a BOM engineer authors recipes without `inventory:create`, which also carries product creation and stock adjustments. Refuses a finished good that is not stock-tracked, a component that is the finished good, scrap at 100%, and an effectivity window that closes before it opens. `outputs` declares what else a run makes — a co-product shares the run's cost, a by-product is credited at what it fetches; omit the field to leave a recipe's outputs alone and send an empty list to clear them. `kind` is `recipe` (the default, and what every recipe in every tenant is) or `kit`: a pack sold as ONE invoice line whose components leave the shelf when the document posts and whose cost of sales is what those components actually cost. A kit is never built and its parent product must not be stock-tracked.", "operationId": "postApiBom", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBomRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBomResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/copy": { "post": { "tags": [ "Bills of materials" ], "summary": "The same recipe again, as a DRAFT — onto the same product (the next free version) or onto another one, carrying every line with its own scrap, note, make/buy override, day offset, date window and position. Copying is the road to a revision: without it an engineering change means retyping every line or editing the recipe the factory is building from, which is refused to an author. Every field is optional and the server fills in what the body does not say, from the same rule the dialog suggests with. `bom:create`, because a copy is a new recipe — and a copy is never the default.", "operationId": "postApiBomByBomIdCopy", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetProductId": { "type": "string" }, "targetVariantId": { "type": "string" }, "version": { "type": "string" }, "name": { "type": "string" } } }, "example": { "targetProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "targetVariantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "version": "2", "name": "Karoo Fresh Holdings Ltd" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBomResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/replace-component": { "post": { "tags": [ "Bills of materials" ], "summary": "Swap one component for another across every recipe that uses it, or keep the part and change how much of it each recipe takes. A draft changes in place; a recipe IN FORCE gets a new draft copy for an approver rather than being changed under the factory; an archived one is left alone with its reason. `preview: true` writes nothing and answers the same list the apply acts on, so a dialog cannot show one thing and do another. An empty `bomIds` means every recipe that uses the part. `bom:edit`, plus `bom:create` when a recipe in force is in scope.", "operationId": "postApiBomReplaceComponent", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "oldProductId": { "type": "string" }, "newProductId": { "type": "string" }, "qtyFactor": { "type": "number" }, "bomIds": { "type": "array", "items": { "type": "string" } }, "preview": { "type": "boolean" } } }, "example": { "oldProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "newProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyFactor": 2.0, "bomIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "preview": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "boolean" }, "edited": { "type": "integer" }, "drafted": { "type": "integer" }, "refused": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "bomId": { "type": "string" }, "bomName": { "type": "string" }, "version": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "status": { "type": "string" }, "outcome": { "type": "string" }, "reason": { "type": "null" }, "lines": { "type": "integer" }, "newBomId": { "type": "string" } } } } } }, "example": { "preview": false, "edited": 2, "drafted": 1, "refused": 1, "rows": [ { "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomName": "Standard build", "version": "1", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "status": "active", "outcome": "NEW_DRAFT", "reason": null, "lines": 2, "newBomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/export": { "get": { "tags": [ "Bills of materials" ], "summary": "Every recipe as a CSV, one row per component line, with the recipe's own fields repeated on each. The column shape is the one the import reads, so export → edit in a spreadsheet → import round-trips. Archived recipes are included — they are the record of how units already built were costed — and `?status=` narrows it. A recipe with no components still exports, as one row with the component columns empty, so re-importing the file cannot silently lose it. Capped at 500 recipes — past that it REFUSES and says to narrow by status, because a file that stopped silently at 500 re-imports as one that simply omits the rest. `bom:export`.", "operationId": "getApiBomExport", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "active" } ], "responses": { "200": { "description": "A CSV download.", "content": { "text/csv": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/document": { "get": { "tags": [ "Bills of materials" ], "summary": "The recipe as a sheet to print — `format=pdf` (the default) or `format=html`. Carries the structure indented level by level, the quantities, positions and line notes, the cost broken out, where the part is used, and the controlled-document facts an audit asks for: whose recipe it is, which version, which revision, who approved it and when, and the date it was printed. A draft and an archived recipe print too — a draft is checked on paper before anybody approves it, and an archived one is the record of how units already built were costed — and each says on the sheet that it is not in force. `bom:view`, not `bom:export`: everything on the sheet is what the screen already shows the same person.", "operationId": "getApiBomByBomIdDocument", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "pdf" }, { "name": "qty", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" } ], "responses": { "200": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/lines/{lineId}/alternates": { "get": { "tags": [ "Bills of materials" ], "summary": "The approved equivalents for one component — the parts that may stand in for it when it is short. Each carries how many of the alternate stand in for one of the primary and what the stores can actually draw of it, because \"there is an approved alternate\" and \"there is one you could fit today\" are different answers and only the second gets a job moving. Ordered the way the engine tries them: priority first, then the part's name. `bom:view`.", "operationId": "getApiBomLinesByLineIdAlternates", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBomLinesByLineIdAlternatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomLinesByLineIdAlternatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Bills of materials" ], "summary": "Replace a line's approved equivalents. Replacing rather than patching because the set is small, capped at 5 and read as a whole — a partial update of an ordered list is the shape that silently loses the ordering somebody just set. A part cannot be its own alternate and the same part cannot be listed twice, which would double the cover the engine thinks it has. Deliberately NOT a change of substance for approval: an alternate changes nothing about what the recipe says the product IS, and every job already released is unaffected until somebody chooses to substitute on it. `bom:edit`.", "operationId": "putApiBomLinesByLineIdAlternates", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBomLinesByLineIdAlternatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomLinesByLineIdAlternatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/open-jobs": { "get": { "tags": [ "Bills of materials" ], "summary": "Open jobs still building to a superseded version of this recipe — what the offer after an approval counts. A job is listed when it has already pinned a standard and that pin is older than the recipe's last change, or points at a different version; a job that has pinned nothing is not listed, because its standard is fixed at its first issue or completion and it will read the recipe in force on its own. Every listed job carries whether it can be re-pinned and, when it cannot, the reason — a planner offered two of the three jobs on the floor needs to be told what is different about the third. `bom:view` and `mrp:view`.", "operationId": "getApiBomByBomIdOpenJobs", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "workOrderId": { "type": "string" }, "woNumber": { "type": "string" }, "status": { "type": "string" }, "qtyPlanned": { "type": "number" }, "bomId": { "type": "string" }, "bomVersion": { "type": "string" }, "reloadable": { "type": "boolean" }, "blocker": { "type": "string" } } } }, "reloadable": { "type": "integer" }, "offer": { "type": "string" } } }, "example": { "jobs": [ { "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "status": "sent", "qtyPlanned": 1.0, "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomVersion": "1", "reloadable": false, "blocker": "text" } ], "reloadable": 1, "offer": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/attachments": { "get": { "tags": [ "Bills of materials" ], "summary": "The documents filed against a recipe — the drawing, the weld specification, the work instruction, the safety sheet. Each carries a signed URL that expires; a file whose URL could not be signed comes back with a null `url` rather than failing the whole list. `bom:view`, the same gate the recipe itself takes: the drawing is the specification the parts list was written to.", "operationId": "getApiBomByBomIdAttachments", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBomByBomIdAttachmentsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomByBomIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Bills of materials" ], "summary": "File a document against a recipe. Raw bytes with `?filename=` — not multipart and not base64, which inflates a 4 MB scan by a third on exactly the connection this product is designed for. `?caption=` is optional and `?contentType=` is a hint only: what is stored is the type the server chose from its closed list. At most 8 files on a recipe and 15 MB each; a photograph is recompressed, a PDF is stored exactly as it arrived. `bom:edit` — the recipe's approval state is deliberately not consulted, because a drawing is very often approved after the recipe is, and a shop that cannot file the current revision against the live recipe files it in email.", "operationId": "postApiBomByBomIdAttachments", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "filename", "in": "query", "required": false, "description": "The name to give the downloaded file.", "schema": { "type": "string" }, "example": "drawing-rev-C.pdf" }, { "name": "caption", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Serial%20plate%20before%20fitting" }, { "name": "contentType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "application%2Fpdf" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBomByBomIdAttachmentsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomByBomIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/attachments/{linkId}": { "delete": { "tags": [ "Bills of materials" ], "summary": "Take a document off a recipe. Removes the LINK, never the bytes: the same drawing may be referenced from a job card or a sales document, and a recipe is not a place from which somebody should be able to shred the specification an invoice is defended with. Deleting the file itself is `DELETE /api/files/{id}`. `bom:edit`.", "operationId": "deleteApiBomByBomIdAttachmentsByLinkId", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBomByBomIdAttachmentsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomByBomIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/import": { "post": { "tags": [ "Bills of materials" ], "summary": "Recipes from a CSV, one row per component line. Rows group into recipes by the finished good and the VERSION, never by the recipe's name. `?preview=true` writes nothing and answers the same shape the apply does, including which of Ledgr's fields each of the file's columns was read as. An unknown SKU is refused and never created; a recipe that already exists is REPLACED through the same writer a hand edit uses, so approval applies unchanged. Imported recipes land as drafts where the approval step applies. `bom:create`.", "operationId": "postApiBomImport", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "preview", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "boolean" }, "created": { "type": "integer" }, "replaced": { "type": "integer" }, "refused": { "type": "integer" }, "fileErrors": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "productSku": { "type": "string" }, "productName": { "type": "string" }, "recipeName": { "type": "string" }, "version": { "type": "string" }, "lines": { "type": "integer" }, "outcome": { "type": "string" }, "reason": { "type": "null" } } } }, "columns": { "type": "object", "properties": { "Qty per run": { "type": "string" } } } } }, "example": { "preview": false, "created": 2, "replaced": 1, "refused": 1, "fileErrors": [ "Row 7: No quantity on this row" ], "rows": [ { "productSku": "KSW-FG-GATE36", "productName": "Double driveway gate 3.6m", "recipeName": "Standard build", "version": "1", "lines": 4, "outcome": "create", "reason": null } ], "columns": { "Qty per run": "qtyPer" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/revisions/compare": { "get": { "tags": [ "Bills of materials" ], "summary": "Any two revisions of a recipe side by side (BOM-07): the header facts that differ, every component line added, removed or changed with both sides (quantity, unit, scrap, the step it is used at) and the facts that moved, and what each revision rolls up to a unit at today's component costs. The two need not be neighbours. 400 for the same revision twice, 404 for a revision this recipe does not have. `bom:view`.", "operationId": "getApiBomByBomIdRevisionsCompare", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fromRevision", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "2" }, { "name": "toRevision", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "5" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "bomId": { "type": "string" }, "from": { "type": "integer" }, "to": { "type": "integer" }, "fromAt": { "type": "string" }, "toAt": { "type": "string" }, "fromUnitCost": { "type": "number" }, "toUnitCost": { "type": "number" }, "header": { "type": "array", "items": { "type": "object" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "partName": { "type": "string" }, "change": { "type": "string" }, "changed": { "type": "array", "items": { "type": [ "object", "string" ] } }, "after": { "type": "object", "properties": { "qtyPer": { "type": "number" }, "scrapPercent": { "type": "number" }, "operationSeq": { "type": "integer" } } }, "before": { "type": "object", "properties": { "qtyPer": { "type": "number" }, "scrapPercent": { "type": "number" } } } } } }, "unchangedLines": { "type": "integer" } } }, "example": { "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "from": 2, "to": 5, "fromAt": "2026-09-17T14:02:00Z", "toAt": "2026-09-30T10:00:00Z", "fromUnitCost": 28.0, "toUnitCost": 81.0, "header": [], "lines": [ { "partName": "Hinge", "change": "added", "changed": [], "after": { "qtyPer": 2.0, "scrapPercent": 0.0, "operationSeq": 20 } }, { "partName": "Bolt", "change": "changed", "changed": [ "scrap" ], "before": { "qtyPer": 10.0, "scrapPercent": 0.0 }, "after": { "qtyPer": 10.0, "scrapPercent": 5.0 } } ], "unchangedLines": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/revisions": { "get": { "tags": [ "Bills of materials" ], "summary": "What this recipe said at each point in its life, newest first (bounded at 100). Each revision holds the whole recipe as it stood after that change, and `changes` is the difference from the revision before it, worked out at read time so the wording improves for revisions already stored. A recipe changed before this shipped has no history, which is not the same as nothing having happened to it. `bom:view`.", "operationId": "getApiBomByBomIdRevisions", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "revisionNo": { "type": "integer" }, "kind": { "type": "string" }, "note": { "type": "string" }, "changedByName": { "type": "string" }, "changedAt": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string" }, "lineCount": { "type": "integer" }, "changes": { "type": "array", "items": { "type": "string" } } } } }, "example": [ { "revisionNo": 3, "kind": "approved", "note": "Checked against the drawing.", "changedByName": "Thandi Mokoena", "changedAt": "2026-09-01T09:15:00Z", "name": "Standard build", "version": "2", "status": "active", "lineCount": 4, "changes": [ "Status awaiting approval → in force" ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/revisions/{revisionNo}/restore": { "post": { "tags": [ "Bills of materials" ], "summary": "Put an earlier revision back — as a new DRAFT, never over the recipe in force, because deciding that an old recipe is what the factory should build again is an approver's decision. The draft is raised through the same writer as a recipe typed by hand, so every rule applies to it, and its version is suggested the way a copy's is. `bom:view` to read the history and `bom:create` to make the draft.", "operationId": "postApiBomByBomIdRevisionsByRevisionNoRestore", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revisionNo", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" } } }, "example": { "version": "2 restored" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "outputQty": { "type": "number" }, "status": { "type": "string" }, "lineCount": { "type": "integer" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Standard build", "version": "3", "outputQty": 1.0, "status": "draft", "lineCount": 4 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/pending": { "get": { "tags": [ "Bills of materials" ], "summary": "The approver's queue — every recipe awaiting a decision, oldest submission first. Gated on `bom:view`, not `bom:approve`: an author needs to see that their own submission is still sitting there, and hiding the queue from them is how people start asking in person.", "operationId": "getApiBomPending", "description": "Requires the `bom:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBomResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "productSku": "LEN-TP-14G4", "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "version": "1", "outputQty": 3.0, "labourCost": 10005.0, "overheadCost": 10005.0, "status": "sent", "notes": "Budget deferred to the next financial year.", "lineCount": 3, "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentVariantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "componentName": "Karoo Fresh Holdings Ltd", "componentSku": "LEN-TP-14G4", "qtyPer": 1.0, "scrapPercent": 15.0, "notes": "Budget deferred to the next financial year.", "sortOrder": 1 } ], "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "submittedAt": "2026-09-01T09:15:00Z", "submittedByName": "Thandi Mokoena", "approvedAt": "2026-09-01T09:15:00Z", "approvedByName": "Thandi Mokoena", "decisionNote": "Budget deferred to the next financial year.", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena", "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/submit": { "post": { "tags": [ "Bills of materials" ], "summary": "Ask for a decision. `bom:edit` — submitting is the author's act. Refuses a recipe with no components: there is nothing to approve about one, and a button that always 400s is how people learn to ignore a workflow.", "operationId": "postApiBomByBomIdSubmit", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBomResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/approve": { "post": { "tags": [ "Bills of materials" ], "summary": "Put a recipe into force. `bom:approve`. There is deliberately NO self-approval refusal — nothing in Ledgr has one, the control is which roles hold the permission, and a three-user tenant with one engineer would otherwise never activate a recipe. Both actors are recorded.", "operationId": "postApiBomByBomIdApprove", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomByBomIdRejectRequest" }, "example": { "note": "Checked against drawing rev C" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBomResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/bom/{bomId}/reject": { "post": { "tags": [ "Bills of materials" ], "summary": "Send a recipe back to draft with a reason. `bom:approve`, and the reason is REQUIRED — a rejection with no reason means the author resubmits the same recipe.", "operationId": "postApiBomByBomIdReject", "description": "Requires the `bom:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "bom:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomByBomIdRejectRequest" }, "example": { "note": "The beam quantity is per pair, not per frame" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBomResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBomResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/runs": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "MRP runs and their outcomes.", "operationId": "getApiMrpRuns", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpRunsResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "runNumber": "INV-0001", "name": "Karoo Fresh Holdings Ltd", "status": "sent", "horizonStart": "2026-09-01", "horizonEnd": "2026-09-30", "bucketDays": 30, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "includeSafetyStock": true, "includeOnOrder": true, "netOffPlannedOrders": true, "supersedesRunId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "plannedOrderCount": 3, "purchaseOrderCount": 3, "productionOrderCount": 3, "exceptionCount": 3, "demandLineCount": 3, "productCount": 3, "maxLevel": 1, "totalPlannedValue": 10005.0, "unplannedDemandCount": 3, "convertedCount": 3, "durationMs": 1, "errorText": "text", "startedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "createdByName": "Thandi Mokoena", "kind": "standard", "whatIfDemandPercent": 15, "whatIfProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "whatIfProductName": "Karoo Fresh Holdings Ltd", "whatIfExtraLeadDays": 30 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Material planning (MRP)" ], "summary": "Run MRP across the planning horizon.", "operationId": "postApiMrpRuns", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "horizonStart": { "type": "string", "format": "date" }, "horizonEnd": { "type": "string", "format": "date" }, "bucketDays": { "type": "integer" }, "locationId": { "type": "string" }, "includeSafetyStock": { "type": "boolean" }, "includeOnOrder": { "type": "boolean" }, "includeForecast": { "type": "boolean" }, "includeReorderPoints": { "type": "boolean" }, "netOffPlannedOrders": { "type": "boolean" }, "includeDraftBoms": { "type": "boolean" }, "productIds": { "type": "array", "items": { "type": "string" } }, "fenceOneDays": { "type": "integer" }, "fenceTwoDays": { "type": "integer" }, "includeDraftQuotes": { "type": "boolean" }, "simulation": { "type": "boolean" }, "whatIfDemandPercent": { "type": "integer" }, "whatIfProductId": { "type": "string" }, "whatIfExtraLeadDays": { "type": "integer" } } }, "example": { "name": "Karoo Fresh Holdings Ltd", "horizonStart": "2026-09-01", "horizonEnd": "2026-09-30", "bucketDays": 7, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "includeSafetyStock": true, "includeOnOrder": true, "includeForecast": true, "includeReorderPoints": true, "netOffPlannedOrders": true, "includeDraftBoms": false, "productIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "fenceOneDays": 14, "fenceTwoDays": 180, "includeDraftQuotes": false, "simulation": false, "whatIfDemandPercent": 100, "whatIfProductId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "whatIfExtraLeadDays": 30 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpRunsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpRunsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/runs/latest": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "The most recent run, which is what the screen opens on.", "operationId": "getApiMrpRunsLatest", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpRunsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpRunsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/available-to-promise": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "What can still be promised per product, and from when: on hand plus firm receipts (sent purchase orders, jobs on the floor) less firm commitments (customer demand, parts owed to jobs). productIds is a comma-separated list of at most 100; excludeDocumentId leaves out the document being edited.", "operationId": "getApiMrpAvailableToPromise", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productIds", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03,8d2e4b17-9c3a-4f60-b5d1-7e0a2c9f4b86" }, { "name": "excludeDocumentId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "5a714b17-9c3a-4f60-b5d1-7e0a2c9f4b86" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "onHand": { "type": "number" }, "now": { "type": "number" }, "later": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "qty": { "type": "number" } } } }, "overcommitted": { "type": "boolean" }, "qtyPrecision": { "type": "integer" } } } }, "example": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "onHand": 1.0, "now": 1.0, "later": [ { "from": "2026-09-01", "qty": 3.0 } ], "overcommitted": true, "qtyPrecision": 3 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/delivery-promise": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "When a quantity of a product can be delivered, and the one thing that decides it: stock and firm receipts first, else the recipe and each item's lead time over the shop calendar. productId and qty are required; excludeDocumentId leaves out the document being edited. No date is given for an item with no lead time on record.", "operationId": "getApiMrpDeliveryPromise", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "qty": { "type": "number" }, "date": { "type": "string", "format": "date" }, "bindingName": { "type": "string" }, "reason": { "type": "string" }, "leadTimeDays": { "type": "integer" }, "basis": { "type": "string" }, "qtyPrecision": { "type": "integer" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qty": 3.0, "date": "2026-09-01", "bindingName": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year.", "leadTimeDays": 30, "basis": "invoice", "qtyPrecision": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/runs/{id}": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "One run — its planned orders, exceptions and the time-phased grid.", "operationId": "getApiMrpRunsById", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpRunsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpRunsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/planned-orders/{id}/firm": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Firm a recommendation so the next run stops moving it.", "operationId": "postApiMrpPlannedOrdersByIdFirm", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/planned-orders/{id}": { "patch": { "tags": [ "Material planning (MRP)" ], "summary": "Change a recommendation's quantity, dates or supplier before converting it. The recommendation is pinned; the supplier's minimum, the pack multiple and whole runs are warned about, not refused.", "operationId": "patchApiMrpPlannedOrdersById", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "qtyOrdered": { "type": "number" }, "requiredDate": { "type": "string", "format": "date" }, "releaseDate": { "type": "string", "format": "date" }, "supplierId": { "type": "string" } } }, "example": { "qtyOrdered": 50.0, "requiredDate": "2026-10-20", "releaseDate": "2026-10-13", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "qtyOrdered": { "type": "number" }, "requiredDate": { "type": "string", "format": "date" }, "releaseDate": { "type": "string", "format": "date" }, "supplierId": { "type": "string" }, "estimatedCost": { "type": "number" }, "warnings": { "type": "array", "items": { "type": "object" } } } }, "example": { "status": "sent", "qtyOrdered": 1.0, "requiredDate": "2026-09-01", "releaseDate": "2026-09-01", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "estimatedCost": 10005.0, "warnings": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/planned-orders/{id}/cancel": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Discard a recommendation.", "operationId": "postApiMrpPlannedOrdersByIdCancel", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/runs/{id}/production-schedule": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "The production schedule of a run: each finished item the shop makes to stock (made, at the top of its recipes), week by week over the run's buckets — forecast, firm demand, what the plan nets, receipts already on the way, the build (recommendations, pins and schedule lines) and whether the planner set it. `editable` is true only for the newest live plan.", "operationId": "getApiMrpRunsByIdProductionSchedule", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpProductionScheduleResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpProductionScheduleResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/production-schedule": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Set a week's build on the current plan: every open plan line building that item that week is cancelled and one firm schedule line of the quantity takes its place (0 leaves none). The next run nets it as supply and buys or makes its parts. A what-if or a replaced plan is refused (409); a part rather than a finished made item is refused (400). Answers with the schedule as it now stands.", "operationId": "postApiMrpProductionSchedule", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string" }, "productId": { "type": "string" }, "bucketIndex": { "type": "integer" }, "qty": { "type": "number" } } }, "example": { "runId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "8c1e2f40-9d3a-4b7e-a1c2-5f6e7d8c9b0a", "bucketIndex": 4, "qty": 50.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpProductionScheduleResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpProductionScheduleResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/outside-work/convert": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Put outside work (the purchase a subcontracted step of a job needs) onto requisitions, one per subcontractor. Each line is a service with no item, named for the step, the item and the job; ordered and received, it bills to 5067 and books the step it was for. A row whose route names no subcontractor is skipped with the reason. Needs mrp:create and procurement:create; a what-if's outside work is refused (409).", "operationId": "postApiMrpOutsideWorkConvert", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outsideWorkIds": { "type": "array", "items": { "type": "string" } }, "submitImmediately": { "type": "boolean" } } }, "example": { "outsideWorkIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "submitImmediately": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpConvertResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpConvertResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/outside-work/{id}/cancel": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Drop a piece of outside work from this plan. Only planned outside work can be dropped (409 otherwise, or on a what-if).", "operationId": "postApiMrpOutsideWorkByIdCancel", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/supply-rules": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "Which locations are planned on their own and refilled from another, with the days on the road. A location with a rule is netted by itself (its stock, stock on the road to it, its located forecast, its reorder point); every other location is the main pool. Needs mrp:view.", "operationId": "getApiMrpSupplyRules", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpSupplyRulesResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiMrpSupplyRulesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Material planning (MRP)" ], "summary": "Refill a location from another, replacing that location's rule. Refused (400) when it would refill a location from itself, directly or round a loop, or with more than 365 days on the road. Answers the rules as they now stand. Needs mrp:edit.", "operationId": "putApiMrpSupplyRules", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string" }, "sourceLocationId": { "type": "string" }, "leadDays": { "type": "integer" } } }, "example": { "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sourceLocationId": "8c2d4e61-0a7b-4f39-b5d2-91e6c3a8f7b4", "leadDays": 3 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpSupplyRulesResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiMrpSupplyRulesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/supply-rules/{locationId}": { "delete": { "tags": [ "Material planning (MRP)" ], "summary": "Stop refilling a location; it rejoins the main pool on the next run. 404 when it has no rule. Answers the rules as they now stand. Needs mrp:edit.", "operationId": "deleteApiMrpSupplyRulesByLocationId", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/transfers/{id}/ship": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Put a planned transfer on the road: an in-transit stock transfer from the source to the location it refills, refused (400) past what the source holds. Only a planned transfer ships (409 otherwise, or on a what-if). Needs mrp:create and inventory:create.", "operationId": "postApiMrpTransfersByIdShip", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "sku": { "type": "string" }, "fromLocationId": { "type": "string" }, "fromLocationName": { "type": "string" }, "toLocationId": { "type": "string" }, "toLocationName": { "type": "string" }, "qty": { "type": "number" }, "shipDate": { "type": "string", "format": "date" }, "arriveDate": { "type": "string", "format": "date" }, "neededDate": { "type": "string", "format": "date" }, "lateDays": { "type": "integer" }, "status": { "type": "string" }, "stockTransferId": { "type": "string" } } }, "example": { "id": "b41c7e09-6d2a-4f85-9e3b-0c58a1f7d264", "productId": "e7a90c35-1b4d-4c62-a8f0-5d93b2e61c7a", "productName": "Hex bolt M12 x 50", "sku": "BOLT-M12-50", "fromLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromLocationName": "Johannesburg factory", "toLocationId": "8c2d4e61-0a7b-4f39-b5d2-91e6c3a8f7b4", "toLocationName": "Durban branch", "qty": 30.0, "shipDate": "2026-10-16", "arriveDate": "2026-10-19", "neededDate": "2026-10-19", "lateDays": 0, "status": "shipped", "stockTransferId": "9f2b6c41-7e08-4d3a-b1c5-68e4a02d9f17" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/transfers/{id}/cancel": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Drop a planned transfer from this plan. Only a planned one can be dropped (409 otherwise, or on a what-if). Needs mrp:edit.", "operationId": "postApiMrpTransfersByIdCancel", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "sku": { "type": "string" }, "fromLocationId": { "type": "string" }, "fromLocationName": { "type": "string" }, "toLocationId": { "type": "string" }, "toLocationName": { "type": "string" }, "qty": { "type": "number" }, "shipDate": { "type": "string", "format": "date" }, "arriveDate": { "type": "string", "format": "date" }, "neededDate": { "type": "string", "format": "date" }, "lateDays": { "type": "integer" }, "status": { "type": "string" } } }, "example": { "id": "b41c7e09-6d2a-4f85-9e3b-0c58a1f7d264", "productId": "e7a90c35-1b4d-4c62-a8f0-5d93b2e61c7a", "productName": "Hex bolt M12 x 50", "sku": "BOLT-M12-50", "fromLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromLocationName": "Johannesburg factory", "toLocationId": "8c2d4e61-0a7b-4f39-b5d2-91e6c3a8f7b4", "toLocationName": "Durban branch", "qty": 30.0, "shipDate": "2026-10-16", "arriveDate": "2026-10-19", "neededDate": "2026-10-19", "lateDays": 0, "status": "cancelled" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/convert": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Split recommendations into requisitions for the buy side and work orders for the make side.", "operationId": "postApiMrpConvert", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plannedOrderIds": { "type": "array", "items": { "type": "string" } }, "groupBySupplier": { "type": "boolean" }, "requisitionTitle": { "type": "string" }, "notes": { "type": "string" }, "submitImmediately": { "type": "boolean" } } }, "example": { "plannedOrderIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "groupBySupplier": true, "requisitionTitle": "Karoo Fresh Holdings Ltd", "notes": "Budget deferred to the next financial year.", "submitImmediately": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpConvertResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpConvertResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/replan-settings": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "Whether the morning replan orders what it plans (Material Planning → Order these each morning). Off by default.", "operationId": "getApiMrpReplanSettings", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiMrpReplanSettingsRequest" }, "example": { "firmPlannedOrders": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Material planning (MRP)" ], "summary": "Turn the morning replan's ordering on or off. Needs mrp:create and procurement:create — it raises both work orders and purchase requests.", "operationId": "putApiMrpReplanSettings", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiMrpReplanSettingsRequest" }, "example": { "firmPlannedOrders": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiMrpReplanSettingsRequest" }, "example": { "firmPlannedOrders": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/forecasts": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "Demand forecasts feeding the run.", "operationId": "getApiMrpForecasts", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "locationId": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "qty": { "type": "number" }, "kind": { "type": "string" }, "consumedQty": { "type": "number" }, "remainingQty": { "type": "number" }, "notes": { "type": "string" }, "method": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodStart": "2026-09-01", "qty": 3.0, "kind": "standard", "consumedQty": 3.0, "remainingQty": 3.0, "notes": "Budget deferred to the next financial year.", "method": "smoothed" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Material planning (MRP)" ], "summary": "Add a forecast.", "operationId": "postApiMrpForecasts", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "periodStart": { "type": "string" }, "qty": { "type": "number" }, "kind": { "type": "string" }, "locationId": { "type": "string" }, "notes": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodStart": "2026-10", "qty": 400.0, "kind": "forecast", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpForecastsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/forecast-suggestion": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "A forecast suggested from what an item sold: its monthly sales (invoices net of credit notes, from its first sale, at most 36 months, not the month in progress), the method that would have been closest on the latest months held back (3-month average, smoothed average, or same month last year), how many units a month it was out by, and a figure for each of the next `months` (1–12, default 3) from next month. Needs productId. With under six months of sales, `blocker` says why and nothing is suggested. Writes nothing.", "operationId": "getApiMrpForecastSuggestion", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "months", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "3" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "productName": { "type": "string" }, "sku": { "type": "string" }, "qtyPrecision": { "type": "integer" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpForecastSuggestionResponseMonthsItem" } }, "blocker": { "type": "null" }, "method": { "type": "string" }, "methodLabel": { "type": "string" }, "meanAbsoluteError": { "type": "number" }, "months": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpForecastSuggestionResponseMonthsItem" } } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Workshop trolley", "sku": "KSW-FG-TROLLEY", "qtyPrecision": 0, "history": [ { "month": "2026-06-01", "qty": 10.0 }, { "month": "2026-07-01", "qty": 6.0 }, { "month": "2026-08-01", "qty": 10.0 } ], "blocker": null, "method": "smoothed", "methodLabel": "Smoothed average — recent months count for more", "meanAbsoluteError": 2.0, "months": [ { "month": "2026-10-01", "qty": 9.0 }, { "month": "2026-11-01", "qty": 9.0 }, { "month": "2026-12-01", "qty": 9.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/forecast-suggestion/accept": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Accept a suggestion: each month (perhaps edited) becomes an ordinary forecast line carrying the method, in one transaction. A month at zero adds nothing; this month or a past one is refused (400), as is an unknown method.", "operationId": "postApiMrpForecastSuggestionAccept", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "method": { "type": "string" }, "months": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpForecastSuggestionResponseMonthsItem" } } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "method": "smoothed", "months": [ { "month": "2026-11-01", "qty": 12.0 } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "string" } } }, "example": { "ids": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/forecasts/{id}": { "delete": { "tags": [ "Material planning (MRP)" ], "summary": "Remove a forecast.", "operationId": "deleteApiMrpForecastsById", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/capacity": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "Load against capacity per work centre across the horizon.", "operationId": "getApiMrpCapacity", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "siteId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "5a714b17-9c3a-4f60-b5d1-7e0a2c9f4b86" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "workCentreId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "availableHours": { "type": "number" }, "plannedHours": { "type": "number" }, "loadPercent": { "type": "number" }, "overloadHours": { "type": "number" }, "freeHours": { "type": "number" }, "status": { "type": "string" }, "workingDays": { "type": "integer" }, "operationCount": { "type": "integer" }, "workOrderCount": { "type": "integer" }, "closedDays": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "name": { "type": "string" }, "kind": { "type": "string" } } } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "workOrderId": { "type": "string" }, "woNumber": { "type": "string" }, "sequenceNo": { "type": "integer" }, "description": { "type": "string" }, "hours": { "type": "number" }, "date": { "type": "string", "format": "date" }, "status": { "type": "string" } } } } } } }, "totalAvailableHours": { "type": "number" }, "totalPlannedHours": { "type": "number" }, "overloadedCentreCount": { "type": "integer" }, "unassignedHours": { "type": "number" }, "outsideWindowOperationCount": { "type": "integer" } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "lines": [ { "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "availableHours": 3.0, "plannedHours": 3.0, "loadPercent": 15.0, "overloadHours": 3.0, "freeHours": 3.0, "status": "sent", "workingDays": 30, "operationCount": 3, "workOrderCount": 3, "closedDays": [ { "date": "2026-09-01", "name": "Karoo Fresh Holdings Ltd", "kind": "standard" } ], "jobs": [ { "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "sequenceNo": 1, "description": "Consulting services — August 2026", "hours": 3.0, "date": "2026-09-01", "status": "sent" } ] } ], "totalAvailableHours": 3.0, "totalPlannedHours": 3.0, "overloadedCentreCount": 3, "unassignedHours": 3.0, "outsideWindowOperationCount": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/calendar": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "The manufacturing calendar — working days, shifts and shutdowns.", "operationId": "getApiMrpCalendar", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "publicHolidays": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "name": { "type": "string" }, "isObserved": { "type": "boolean" } } } }, "exceptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "name": { "type": "string" }, "isWorking": { "type": "boolean" }, "workCentreId": { "type": "string" }, "workCentreCode": { "type": "string" }, "notes": { "type": "string" } } } } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "publicHolidays": [ { "date": "2026-09-01", "name": "Karoo Fresh Holdings Ltd", "isObserved": false } ], "exceptions": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "name": "Karoo Fresh Holdings Ltd", "isWorking": false, "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workCentreCode": "CT-001", "notes": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Material planning (MRP)" ], "summary": "Add a calendar entry.", "operationId": "postApiMrpCalendar", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "toDate": { "type": "string", "format": "date" }, "name": { "type": "string" }, "isWorking": { "type": "boolean" }, "workCentreId": { "type": "string" }, "notes": { "type": "string" } } }, "example": { "date": "2026-12-25", "toDate": "2026-09-01", "name": "Karoo Fresh Holdings Ltd", "isWorking": false, "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Public holiday" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpCalendarResponse" }, "example": { "status": "saved", "days": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Material planning (MRP)" ], "summary": "Clear a range of calendar entries.", "operationId": "deleteApiMrpCalendar", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "example": "logo.png" }, { "name": "workCentreId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpCalendarResponse" }, "example": { "status": "deleted", "days": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/calendar/{id}": { "delete": { "tags": [ "Material planning (MRP)" ], "summary": "Remove one calendar entry.", "operationId": "deleteApiMrpCalendarById", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/work-centres": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "Work centres, their capacity and their rates.", "operationId": "getApiMrpWorkCentres", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpWorkCentresResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "kind": "standard", "capacityHoursPerDay": 3.0, "machineCount": 1, "efficiencyPercent": 15.0, "workingDays": [ 30 ], "queueDays": 30, "labourRatePerHour": 1.0, "overheadRatePerHour": 1.0, "isSubcontract": false, "observePublicHolidays": true, "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "active": true, "notes": "Budget deferred to the next financial year.", "dailyEffectiveHours": 3.0, "routingOperationCount": 3, "openOperationCount": 3 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Material planning (MRP)" ], "summary": "Add a work centre.", "operationId": "postApiMrpWorkCentres", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpWorkCentresRequest" }, "example": { "code": "WELD-01", "name": "Welding bay 1", "description": "Consulting services — August 2026", "kind": "standard", "capacityHoursPerDay": 8.0, "machineCount": 3, "efficiencyPercent": 15.0, "workingDays": [ 30 ], "queueDays": 30, "labourRatePerHour": 420.0, "overheadRatePerHour": 1.0, "isSubcontract": true, "observePublicHolidays": true, "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "active": true, "notes": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpWorkCentresResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpWorkCentresResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/work-centres/{id}": { "put": { "tags": [ "Material planning (MRP)" ], "summary": "Update a work centre.", "operationId": "putApiMrpWorkCentresById", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpWorkCentresRequest" }, "example": { "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "kind": "standard", "capacityHoursPerDay": 16.0, "machineCount": 3, "efficiencyPercent": 15.0, "workingDays": [ 30 ], "queueDays": 30, "labourRatePerHour": 1.0, "overheadRatePerHour": 1.0, "isSubcontract": true, "observePublicHolidays": true, "supplierContactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "active": true, "notes": "Budget deferred to the next financial year." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpWorkCentresResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpWorkCentresResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Material planning (MRP)" ], "summary": "Remove a work centre.", "operationId": "deleteApiMrpWorkCentresById", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/routings": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "Routings — the ordered operations a part goes through.", "operationId": "getApiMrpRoutings", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "qty", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRoutingsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomName": "Karoo Fresh Holdings Ltd", "name": "Karoo Fresh Holdings Ltd", "version": "1", "status": "sent", "isDefault": true, "expectedYieldPercent": 15.0, "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "notes": "Budget deferred to the next financial year.", "operations": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sequenceNo": 1, "description": "Consulting services — August 2026", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workCentreCode": "CT-001", "workCentreName": "Karoo Fresh Holdings Ltd", "setupHours": 3.0, "runHoursPerUnit": 3.0, "isSubcontract": false, "subcontractSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subcontractSupplierName": "Karoo Fresh Holdings Ltd", "subcontractCostPerUnit": 10005.0, "subcontractLeadDays": 30, "instructions": "Budget deferred to the next financial year.", "hoursForQty": 3.0, "costForQty": 3.0 } ], "qty": 3.0, "startedQty": 3.0, "setupHours": 3.0, "runHours": 3.0, "totalHours": 3.0, "labourCost": 10005.0, "overheadCost": 10005.0, "subcontractCost": 10005.0, "totalCost": 10005.0, "costPerUnit": 10005.0, "unassignedOperationCount": 3 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Material planning (MRP)" ], "summary": "Create a routing.", "operationId": "postApiMrpRoutings", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "bomId": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string" }, "isDefault": { "type": "boolean" }, "expectedYieldPercent": { "type": "number" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" }, "notes": { "type": "string" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpRoutingsByIdOperationsRequest" } } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Standard frame route", "version": "1", "status": "sent", "isDefault": true, "expectedYieldPercent": 15.0, "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "notes": "Budget deferred to the next financial year.", "operations": [ { "sequenceNo": 1, "description": "Consulting services — August 2026", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "setupHours": 3.0, "runHoursPerUnit": 3.0, "isSubcontract": true, "subcontractSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subcontractCostPerUnit": 10005.0, "subcontractLeadDays": 30, "instructions": "Budget deferred to the next financial year." } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpRoutingsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpRoutingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/routings/{id}": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "One routing and its operations.", "operationId": "getApiMrpRoutingsById", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "qty", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpRoutingsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpRoutingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Material planning (MRP)" ], "summary": "Update a routing.", "operationId": "putApiMrpRoutingsById", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bomId": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string" }, "isDefault": { "type": "boolean" }, "expectedYieldPercent": { "type": "number" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" }, "notes": { "type": "string" } } }, "example": { "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Standard frame route rev B", "version": "1", "status": "sent", "isDefault": true, "expectedYieldPercent": 15.0, "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpRoutingsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpRoutingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Material planning (MRP)" ], "summary": "Delete a routing.", "operationId": "deleteApiMrpRoutingsById", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/routings/{id}/operations": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Add an operation to a routing.", "operationId": "postApiMrpRoutingsByIdOperations", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpRoutingsByIdOperationsRequest" }, "example": { "sequenceNo": 10, "description": "Consulting services — August 2026", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "setupHours": 0.5, "runHoursPerUnit": 0.05, "isSubcontract": true, "subcontractSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subcontractCostPerUnit": 10005.0, "subcontractLeadDays": 30, "instructions": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpRoutingsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpRoutingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/routings/operations/{opId}": { "put": { "tags": [ "Material planning (MRP)" ], "summary": "Change an operation.", "operationId": "putApiMrpRoutingsOperationsByOpId", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpRoutingsByIdOperationsRequest" }, "example": { "sequenceNo": 1, "description": "Consulting services — August 2026", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "setupHours": 3.0, "runHoursPerUnit": 0.05, "isSubcontract": true, "subcontractSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subcontractCostPerUnit": 10005.0, "subcontractLeadDays": 30, "instructions": "Budget deferred to the next financial year." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "updated" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Material planning (MRP)" ], "summary": "Remove an operation.", "operationId": "deleteApiMrpRoutingsOperationsByOpId", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/routings/operations/{opId}/attachments": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "The files filed against a route step — the drawing, the jig set-up photograph, the weld procedure the operator works from. Each carries a signed URL that expires; a file whose URL could not be signed comes back with a null `url`. `mrp:view`, the gate the route itself takes.", "operationId": "getApiMrpRoutingsOperationsByOpIdAttachments", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBomByBomIdAttachmentsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomByBomIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Material planning (MRP)" ], "summary": "File a document against a route step. Raw bytes with `?filename=`, the same shape and limits as a recipe's files: at most 8 on a step and 15 MB each; a photograph is recompressed, a PDF is stored as it arrived. `?caption=` is optional and `?contentType=` a hint only. `mrp:edit`.", "operationId": "postApiMrpRoutingsOperationsByOpIdAttachments", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "filename", "in": "query", "required": false, "description": "The name to give the downloaded file.", "schema": { "type": "string" }, "example": "weld-procedure-rev-B.pdf" }, { "name": "caption", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Serial%20plate%20before%20fitting" }, { "name": "contentType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "application%2Fpdf" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBomByBomIdAttachmentsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomByBomIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/routings/operations/{opId}/attachments/{linkId}": { "delete": { "tags": [ "Material planning (MRP)" ], "summary": "Take a file off a route step. Removes the LINK, never the bytes. `mrp:edit`.", "operationId": "deleteApiMrpRoutingsOperationsByOpIdAttachmentsByLinkId", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBomByBomIdAttachmentsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomByBomIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/attachments": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "The files of the route step this order step was released from — what the operator opens at the machine. A step added to the order by hand has no route step and no files. `mrp:view`.", "operationId": "getApiWorkOrdersOperationsByOpIdAttachments", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBomByBomIdAttachmentsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBomByBomIdAttachmentsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/floor-queue": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "Operator mode's queue: every open step of a released or started order, highest priority first, with the planner's instructions, the files on its route step, the step it is waiting on and who is clocked on. `shopfloor:view` or `mrp:view`.", "operationId": "getApiWorkOrdersFloorQueue", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "centreId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "operationId": { "type": "string" }, "workOrderId": { "type": "string" }, "woNumber": { "type": "string" }, "productName": { "type": "string" }, "qty": { "type": "number" }, "priority": { "type": "integer" }, "sequenceNo": { "type": "integer" }, "description": { "type": "string" }, "workCentreId": { "type": "string" }, "workCentreName": { "type": "string" }, "status": { "type": "string" }, "plannedHours": { "type": "number" }, "actualHours": { "type": "number" }, "instructions": { "type": "string" }, "attachmentCount": { "type": "integer" }, "scheduledStart": { "type": "string" }, "waitingOn": { "type": "null" }, "runningTimers": { "type": "array", "items": { "type": "object" } } } } } } }, "example": { "items": [ { "operationId": "7d2e1a00-1111-4222-8333-944455556666", "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "WO-0042", "productName": "Driveway gate", "qty": 4.0, "priority": 2, "sequenceNo": 10, "description": "Weld frame", "workCentreId": "0b8e2f11-2222-4333-8444-555566667777", "workCentreName": "Weld bay", "status": "pending", "plannedHours": 6.0, "actualHours": 0.0, "instructions": "Tack all four corners first.", "attachmentCount": 1, "scheduledStart": "2026-10-05T06:00:00Z", "waitingOn": null, "runningTimers": [] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/routings/operations/{opId}/checks": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "The quality checks a route step carries; release copies them onto each order's step. `mrp:view`.", "operationId": "getApiMrpRoutingsOperationsByOpIdChecks", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiMrpRoutingsOperationsByOpIdChecksResponse" }, "example": { "items": [ { "id": "9a1e0a00-1111-4222-8333-944455556666", "label": "Gap between frame and hinge", "kind": "measure", "minValue": 4.5, "maxValue": 5.5, "unit": "mm", "sequenceNo": 10 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Material planning (MRP)" ], "summary": "Add a check to a route step: `kind` is pass_fail or measure; a measurement needs a lowest or highest acceptable value. Orders released from now on carry it. `mrp:edit`.", "operationId": "postApiMrpRoutingsOperationsByOpIdChecks", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiMrpRoutingsOperationsByOpIdChecksResponse" }, "example": { "items": [ { "id": "9a1e0a00-1111-4222-8333-944455556666", "label": "Gap between frame and hinge", "kind": "measure", "minValue": 4.5, "maxValue": 5.5, "unit": "mm", "sequenceNo": 10 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/routings/operations/{opId}/checks/{checkId}": { "delete": { "tags": [ "Material planning (MRP)" ], "summary": "Remove a route step's check. Orders already released keep theirs. `mrp:edit`.", "operationId": "deleteApiMrpRoutingsOperationsByOpIdChecksByCheckId", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "checkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiMrpCheckPlansByIdResponse" }, "example": { "items": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/check-plans": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "The periodic quality checks this company keeps (T-M2.3): a check the clock raises every `everyHours`, not an order. `mrp:view`.", "operationId": "getApiMrpCheckPlans", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpCheckPlansResponse" } } } }, "example": { "items": [ { "id": "4a1e0a00-1111-4222-8333-944455556666", "label": "Cold room temperature", "kind": "measure", "minValue": 0.0, "maxValue": 5.0, "unit": "C", "everyHours": 4, "workCentreId": null, "workCentreCode": null, "active": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Material planning (MRP)" ], "summary": "Keep a periodic check (T-M2.3): `kind` pass_fail or measure, due every 1 to 168 hours on the plant's clock, optionally at one work centre. Its first slot is the one open now. `mrp:edit`.", "operationId": "postApiMrpCheckPlans", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpCheckPlansResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpCheckPlansResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/check-plans/{id}": { "put": { "tags": [ "Material planning (MRP)" ], "summary": "Change a periodic check (T-M2.3); slots already raised keep what they were. `mrp:edit`.", "operationId": "putApiMrpCheckPlansById", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpCheckPlansResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiMrpCheckPlansResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Material planning (MRP)" ], "summary": "Stop keeping a periodic check (T-M2.3); answers the plans still kept. Its log stays. `mrp:edit`.", "operationId": "deleteApiMrpCheckPlansById", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiMrpCheckPlansByIdResponse" }, "example": { "items": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/periodic-checks": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "The HACCP log (T-M2.3): every slot of the last `days` (1 to 92, default 7), newest first; `due` is what is open now and `missed` what passed unrecorded. Raises the open slot first, so it is current whether or not the hourly job has run. `mrp:view`.", "operationId": "getApiMrpPeriodicChecks", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "How many days forward or back the window covers.", "schema": { "type": "integer" }, "example": "7" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpPeriodicChecksResponseItemsItem" } }, "due": { "type": "integer" }, "missed": { "type": "integer" } } }, "example": { "items": [ { "id": "5b2e0a00-1111-4222-8333-944455556666", "planId": "4a1e0a00-1111-4222-8333-944455556666", "label": "Cold room temperature", "kind": "measure", "minValue": 0.0, "maxValue": 5.0, "unit": "C", "workCentreCode": null, "slotStart": "2026-10-12T06:00:00Z", "dueBy": "2026-10-12T10:00:00Z", "result": "pass", "measuredValue": 3.4, "notes": null, "recordedByName": "Thabo Nkosi", "recordedAt": "2026-10-12T07:05:00Z", "missed": false } ], "due": 0, "missed": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/periodic-checks/{id}/record": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Record a slot of a periodic check (T-M2.3): `passed`, or `value` judged against the plan's limits. A slot already recorded is refused, not overwritten; a missed slot may be recorded late and stays marked missed. `mrp:edit`.", "operationId": "postApiMrpPeriodicChecksByIdRecord", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiMrpPeriodicChecksResponseItemsItem" }, "example": { "id": "5b2e0a00-1111-4222-8333-944455556666", "planId": "4a1e0a00-1111-4222-8333-944455556666", "label": "Cold room temperature", "kind": "measure", "minValue": 0.0, "maxValue": 5.0, "unit": "C", "workCentreCode": null, "slotStart": "2026-10-12T06:00:00Z", "dueBy": "2026-10-12T10:00:00Z", "result": "pass", "measuredValue": 3.4, "notes": null, "recordedByName": "Thabo Nkosi", "recordedAt": "2026-10-12T07:05:00Z", "missed": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/checks": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "An order step's checks and what was recorded against each. `shopfloor:view` or `mrp:view`.", "operationId": "getApiWorkOrdersOperationsByOpIdChecks", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersOperationsByOpIdChecksResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersOperationsByOpIdChecksResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/checks/{checkId}/record": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Record a check: `passed` for pass or fail, `value` for a measurement judged against its limits. A failure puts the order on quality hold; a later pass does not lift it. Refused on a closed step. `shopfloor:edit` or `mrp:edit`.", "operationId": "postApiWorkOrdersOperationsChecksByCheckIdRecord", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "checkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersOperationsByOpIdChecksResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersOperationsByOpIdChecksResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/holds": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "Every quality hold an order has had, open first. While one is open nothing the order makes is received into stock. `shopfloor:view` or `mrp:view`.", "operationId": "getApiWorkOrdersByIdHolds", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workOrderId": { "type": "string" }, "operationId": { "type": "string" }, "checkId": { "type": "string" }, "reason": { "type": "string" }, "openedAt": { "type": "string" }, "openedByName": { "type": "string" }, "disposition": { "type": "null" }, "notes": { "type": "null" }, "closedAt": { "type": "null" }, "reworkOrderId": { "type": "null" } } } } } }, "example": { "items": [ { "id": "6c3e0a00-1111-4222-8333-944455556666", "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "operationId": "7d2e1a00-1111-4222-8333-944455556666", "checkId": "8b2e0a00-1111-4222-8333-944455556666", "reason": "Gap between frame and hinge: 5.9 mm", "openedAt": "2026-09-28T08:14:00Z", "openedByName": "Thabo Nkosi", "disposition": null, "notes": null, "closedAt": null, "reworkOrderId": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/holds/{holdId}/resolve": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Decide a quality hold: `disposition` release, rework or scrap; rework and scrap say what, in `notes`. Answers the order's progress, whose `holds` lists what is still undecided. `mrp:edit`.", "operationId": "postApiWorkOrdersHoldsByHoldIdResolve", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "holdId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkOrdersByIdReworkStepResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiWorkOrdersByIdReworkStepResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/rework": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Raise a rework order for units of a received lot. The order's one component is the item itself, issued from that lot by specific identification and received back on completion; its hours show as the rework's cost. `qty` may not exceed what the lot holds. Replay-safe on `clientId`. `mrp:create`.", "operationId": "postApiWorkOrdersRework", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkOrdersReworkResponse" }, "example": { "id": "1a2b3c4d-1111-4222-8333-944455556666", "woNumber": "WO-0046" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/rework-step": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Send units still in an open order to a rework step instead of booking them as scrap. The step is added at the named step's centre and rates; nothing is written off. `mrp:edit`.", "operationId": "postApiWorkOrdersByIdReworkStep", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkOrdersByIdReworkStepResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiWorkOrdersByIdReworkStepResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/non-conformances": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "An order's non-conformances — cards on a Workflows board built from the Non-conformance template that name this order — with the boards one can be raised on, and whether this user may. `mrp:view`.", "operationId": "getApiWorkOrdersByIdNonConformances", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdNonConformancesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdNonConformancesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Material planning (MRP)" ], "summary": "Raise a non-conformance about this order, and optionally a hold or a lot of it: a card on the chosen Non-conformance board that names the order and lot. Needs `mrp:edit`, `workflows:create` and Workflows on the plan. Replay-safe on `clientId`.", "operationId": "postApiWorkOrdersByIdNonConformances", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdNonConformancesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdNonConformancesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/outside-work": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Order an outsourced step's service from its subcontractor: the outside-work row Material Planning would plan, raised without a run, converted to a requisition (submitted for approval unless `submit` is false). The purchase order it becomes books the step on receipt, and the step's `subcontract` shows its price against the step's standard. `qty` defaults to what the step has left. `mrp:create` and `procurement:create`.", "operationId": "postApiWorkOrdersOperationsByOpIdOutsideWork", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "requisitionIds": { "type": "array", "items": { "type": "string" } }, "requisitionNumbers": { "type": "array", "items": { "type": "string" } }, "convertedCount": { "type": "integer" }, "skipped": { "type": "array", "items": { "type": "object" } } } }, "example": { "requisitionIds": [ "8f9e0a00-1111-4222-8333-944455556666" ], "requisitionNumbers": [ "RQ-0012" ], "convertedCount": 1, "skipped": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/children": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "The sub-assembly orders an order has. `mrp:view`.", "operationId": "getApiWorkOrdersByIdChildren", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "raised": { "type": "array", "items": { "type": "object" } }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdChildrenResponseChildrenItem" } }, "skipped": { "type": "array", "items": { "type": "object" } } } }, "example": { "raised": [], "children": [ { "id": "9b8c0a00-1111-4222-8333-944455556666", "woNumber": "WO-0051", "productName": "Gate frame", "qty": 4.0, "status": "planned", "plannedFinish": "2026-10-04" } ], "skipped": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/subassemblies": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Raise an order for each made component this order is short of, finishing the day before it starts. Each is a `subassembly` order whose parent is this one. A bought component, or one already on an open child order, is listed in `skipped` with why. `mrp:create`.", "operationId": "postApiWorkOrdersByIdSubassemblies", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "raised": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdChildrenResponseChildrenItem" } }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdChildrenResponseChildrenItem" } }, "skipped": { "type": "array", "items": { "type": "string" } } } }, "example": { "raised": [ { "id": "9b8c0a00-1111-4222-8333-944455556666", "woNumber": "WO-0051", "productName": "Gate frame", "qty": 4.0, "status": "planned", "plannedFinish": "2026-10-04" } ], "children": [ { "id": "9b8c0a00-1111-4222-8333-944455556666", "woNumber": "WO-0051", "productName": "Gate frame", "qty": 4.0, "status": "planned", "plannedFinish": "2026-10-04" } ], "skipped": [ "Flat bar — bought, not made: Material Planning orders it" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/serial-trace": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "A serial's genealogy: the work order that made it and the serials built into it, level by level. `productId` chooses when two items share a number. `mrp:view`.", "operationId": "getApiMrpSerialTrace", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "serial", "in": "query", "required": false, "schema": { "type": "string" }, "example": "GT-2026-0042" }, { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "root": { "type": "object", "properties": { "serialNumber": { "type": "string" }, "productName": { "type": "string" }, "status": { "type": "string" }, "madeOnWorkOrderId": { "type": "string" }, "madeOnWoNumber": { "type": "string" }, "builtFrom": { "type": "array", "items": { "type": "object", "properties": { "serialNumber": { "type": "string" }, "productName": { "type": "string" }, "status": { "type": "string" }, "madeOnWorkOrderId": { "type": "null" }, "madeOnWoNumber": { "type": "null" }, "builtFrom": { "type": "array", "items": { "type": "object" } } } } } } } } }, "example": { "root": { "serialNumber": "GT-2026-0042", "productName": "Driveway gate", "status": "in_stock", "madeOnWorkOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "madeOnWoNumber": "WO-0042", "builtFrom": [ { "serialNumber": "MTR-88121", "productName": "Gate motor", "status": "consumed", "madeOnWorkOrderId": null, "madeOnWoNumber": null, "builtFrom": [] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/work-centres/{id}/downtime": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "A centre's machine stops, newest first; an open stop has no `endedAt` and its hours run to now. `shopfloor:view` or `mrp:view`.", "operationId": "getApiMrpWorkCentresByIdDowntime", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "required": false, "description": "How many days forward or back the window covers.", "schema": { "type": "integer" }, "example": "30" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpWorkCentresByIdUpResponse" } } } }, "example": { "items": [ { "id": "5c1e0a00-1111-4222-8333-944455556666", "workCentreId": "0b8e2f11-2222-4333-8444-555566667777", "reason": "power", "notes": "Stage 4", "startedAt": "2026-09-28T08:00:00Z", "endedAt": "2026-09-28T10:30:00Z", "hours": 2.5, "startedByName": "Thabo Nkosi" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/work-centres/{id}/down": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Mark a centre down. `reason` is breakdown, maintenance, changeover, power, no_material, no_operator or other. Refused while it is already down. Its lost hours come off the capacity table. `shopfloor:edit` or `mrp:edit`.", "operationId": "postApiMrpWorkCentresByIdDown", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workCentreId": { "type": "string" }, "reason": { "type": "string" }, "notes": { "type": "string" }, "startedAt": { "type": "string" }, "endedAt": { "type": "null" }, "hours": { "type": "number" }, "startedByName": { "type": "string" } } }, "example": { "id": "5c1e0a00-1111-4222-8333-944455556666", "workCentreId": "0b8e2f11-2222-4333-8444-555566667777", "reason": "breakdown", "notes": "Wire feed jammed", "startedAt": "2026-09-28T08:00:00Z", "endedAt": null, "hours": 0.0, "startedByName": "Thabo Nkosi" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/work-centres/{id}/up": { "post": { "tags": [ "Material planning (MRP)" ], "summary": "Mark a centre back up: its open stop ends now. Refused when it is not down. `shopfloor:edit` or `mrp:edit`.", "operationId": "postApiMrpWorkCentresByIdUp", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpWorkCentresByIdUpResponse" }, "example": { "id": "5c1e0a00-1111-4222-8333-944455556666", "workCentreId": "0b8e2f11-2222-4333-8444-555566667777", "reason": "breakdown", "notes": "Wire feed jammed", "startedAt": "2026-09-28T08:00:00Z", "endedAt": "2026-09-28T09:15:00Z", "hours": 1.25, "startedByName": "Thabo Nkosi" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/oee": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "OEE per centre over the last `days` days: availability (open hours less downtime), performance (standard hours earned over hours booked on closed steps, capped at 100% inside OEE) and quality (good over good plus scrapped). A factor with nothing to measure is null, and so is OEE. `mrp:view`.", "operationId": "getApiMrpOee", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "How many days forward or back the window covers.", "schema": { "type": "integer" }, "example": "30" }, { "name": "siteId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "5a714b17-9c3a-4f60-b5d1-7e0a2c9f4b86" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "workCentreId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "openHours": { "type": "number" }, "downtimeHours": { "type": "number" }, "stops": { "type": "integer" }, "topReason": { "type": "string" }, "availabilityPercent": { "type": "number" }, "performancePercent": { "type": "number" }, "qualityPercent": { "type": "number" }, "oeePercent": { "type": "number" }, "downSince": { "type": "null" } } } } } }, "example": { "from": "2026-08-30", "to": "2026-09-28", "lines": [ { "workCentreId": "0b8e2f11-2222-4333-8444-555566667777", "code": "WELD", "name": "Weld bay", "openHours": 168.0, "downtimeHours": 12.5, "stops": 3, "topReason": "power", "availabilityPercent": 92.6, "performancePercent": 88.0, "qualityPercent": 97.5, "oeePercent": 79.4, "downSince": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/workers": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "The people a booking can name — the company's active users, each with the default rate Book labour starts from, or null. `mrp:view`.", "operationId": "getApiMrpWorkers", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiMrpWorkersResponse" }, "example": { "workers": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Thabo Nkosi", "labourRatePerHour": 185.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/workers/performance": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "Hours per worker over a window (the last 30 days by default), and efficiency on the steps that closed: each closed step earns its planned hours, shared between the people who booked it in proportion to their hours on it. `efficiencyPercent` is null with no closed step to measure. `mrp:view`.", "operationId": "getApiMrpWorkersPerformance", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "workers": { "type": "array", "items": { "type": "object", "properties": { "workerId": { "type": "string" }, "name": { "type": "string" }, "hours": { "type": "number" }, "closedStepHours": { "type": "number" }, "earnedHours": { "type": "number" }, "efficiencyPercent": { "type": "number" }, "stepCount": { "type": "integer" } } } } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "workers": [ { "workerId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Thabo Nkosi", "hours": 42.5, "closedStepHours": 38.0, "earnedHours": 34.2, "efficiencyPercent": 90.0, "stepCount": 6 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/workers/{userId}": { "put": { "tags": [ "Material planning (MRP)" ], "summary": "Set a worker's default labour rate, or clear it with `null`. Book labour starts from it; a step booking keeps the step's own frozen centre rate. `mrp:edit`.", "operationId": "putApiMrpWorkersByUserId", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "labourRatePerHour": { "type": "number" } } }, "example": { "labourRatePerHour": 185.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiMrpWorkersResponse" }, "example": { "workers": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Thabo Nkosi", "labourRatePerHour": 185.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/scrap-reasons": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "The scrap reason list.", "operationId": "getApiMrpScrapReasons", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpScrapReasonsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiMrpScrapReasonsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Material planning (MRP)" ], "summary": "Add a scrap reason.", "operationId": "postApiMrpScrapReasons", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "controllable": { "type": "boolean" }, "active": { "type": "boolean" }, "sortOrder": { "type": "integer" } } }, "example": { "code": "weld-porosity", "label": "Weld porosity", "description": "Consulting services — August 2026", "controllable": true, "active": true, "sortOrder": 1 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpScrapReasonsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiMrpScrapReasonsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/scrap-reasons/{code}": { "delete": { "tags": [ "Material planning (MRP)" ], "summary": "Remove a scrap reason.", "operationId": "deleteApiMrpScrapReasonsByCode", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/scrap-analysis": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "Scrap by reason, by part and by work centre.", "operationId": "getApiMrpScrapAnalysis", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-06-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-31" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "totalQty": { "type": "number" }, "totalCost": { "type": "number" }, "eventCount": { "type": "integer" }, "uncontrollableCost": { "type": "number" }, "loadSheddingCost": { "type": "number" }, "byReason": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpScrapAnalysisResponseByReasonItem" } }, "byWorkCentre": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpScrapAnalysisResponseByReasonItem" } }, "byProduct": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpScrapAnalysisResponseByReasonItem" } }, "byOperator": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMrpScrapAnalysisResponseByReasonItem" } }, "recent": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workOrderId": { "type": "string" }, "woNumber": { "type": "string" }, "operationId": { "type": "string" }, "sequenceNo": { "type": "integer" }, "operationDescription": { "type": "string" }, "workCentreId": { "type": "string" }, "workCentreCode": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "qty": { "type": "number" }, "reasonCode": { "type": "string" }, "reasonLabel": { "type": "string" }, "controllable": { "type": "boolean" }, "operatorUserId": { "type": "string" }, "operatorName": { "type": "string" }, "unitCost": { "type": "number" }, "totalCost": { "type": "number" }, "occurredAt": { "type": "string" }, "notes": { "type": "string" } } } } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "totalQty": 3.0, "totalCost": 10005.0, "eventCount": 3, "uncontrollableCost": 10005.0, "loadSheddingCost": 10005.0, "byReason": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd", "qty": 3.0, "cost": 10005.0, "eventCount": 3, "controllable": true, "sharePercent": 15.0 } ], "byWorkCentre": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd", "qty": 3.0, "cost": 10005.0, "eventCount": 3, "controllable": true, "sharePercent": 15.0 } ], "byProduct": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd", "qty": 3.0, "cost": 10005.0, "eventCount": 3, "controllable": true, "sharePercent": 15.0 } ], "byOperator": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd", "qty": 3.0, "cost": 10005.0, "eventCount": 3, "controllable": true, "sharePercent": 15.0 } ], "recent": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "operationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sequenceNo": 1, "operationDescription": "Consulting services — August 2026", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workCentreCode": "CT-001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "qty": 3.0, "reasonCode": "CT-001", "reasonLabel": "Karoo Fresh Holdings Ltd", "controllable": true, "operatorUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "operatorName": "Karoo Fresh Holdings Ltd", "unitCost": 2900.0, "totalCost": 10005.0, "occurredAt": "2026-09-01T09:15:00Z", "notes": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/batch-trace": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "Genealogy: forward from a supplier lot to every job and finished batch that consumed it, backward from a finished batch to every lot inside it.", "operationId": "getApiMrpBatchTrace", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "batchId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string" }, "example": "backward" }, { "name": "batchNumber", "in": "query", "required": false, "schema": { "type": "string" }, "example": "B-2026-0412" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiMrpBatchTraceResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiMrpBatchTraceResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/work-orders/{id}/genealogy": { "get": { "tags": [ "Material planning (MRP)" ], "summary": "The lots that went into one work order's output.", "operationId": "getApiMrpWorkOrdersByIdGenealogy", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiMrpBatchTraceResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiMrpBatchTraceResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders": { "get": { "tags": [ "Production & work orders" ], "summary": "Work orders. The status filter lives here and nowhere else — it is the only way to reach a cancelled or completed order.", "operationId": "getApiWorkOrders", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "released" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomName": "Karoo Fresh Holdings Ltd", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "qtyPlanned": 1.0, "qtyCompleted": 1.0, "status": "sent", "priority": 1, "plannedStart": "2026-09-01", "plannedFinish": "text", "actualStart": "2026-09-01", "actualFinish": "text", "estimatedCost": 10005.0, "actualCost": 10005.0, "assemblyBuildId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "mrpRunNumber": "INV-0001", "notes": "Budget deferred to the next financial year.", "shortages": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "required": 1.0, "onHand": 1.0, "short": 1.0 } ], "canStart": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Production & work orders" ], "summary": "Raise a work order.", "operationId": "postApiWorkOrders", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string" }, "productId": { "type": "string" }, "qty": { "type": "number" }, "bomId": { "type": "string" }, "locationId": { "type": "string" }, "plannedStart": { "type": "string", "format": "date" }, "plannedFinish": { "type": "string", "format": "date" }, "priority": { "type": "integer" }, "notes": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "variantId": "7d2e1a00-1111-4222-8333-944455556666", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qty": 250.0, "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "plannedStart": "2026-09-01", "plannedFinish": "2026-09-05", "priority": 5, "notes": "Budget deferred to the next financial year.", "clientId": "8d2f5a61-3c7e-4b90-a1d4-6e9b2c0f7a15" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "woNumber": { "type": "string" }, "qtyToStart": { "type": "string", "format": "date" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "qtyToStart": "2026-09-01" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/page": { "get": { "tags": [ "Production & work orders" ], "summary": "One page of work orders for the Production list: searched by order number, product, product code or the customer of an order made to order; open work first (priority, then due date), then closed work, latest first. Answers the page and how many match.", "operationId": "getApiWorkOrdersPage", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "gate" }, { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "in_progress" }, { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "woNumber": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "qtyPlanned": { "type": "number" }, "qtyCompleted": { "type": "number" }, "status": { "type": "string" }, "priority": { "type": "integer" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "WO-0042", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Driveway gate 3.6m", "qtyPlanned": 4.0, "qtyCompleted": 1.0, "status": "in_progress", "priority": 2 } ], "total": 53, "page": 1, "limit": 50, "totalPages": 2 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/kpis": { "get": { "tags": [ "Production & work orders" ], "summary": "How the floor is doing over the last `days` (7 to 366, default 90) — how many orders finished and the share finished by their planned finish, units made against units planned, planned hours against booked hours on closed steps, the money in WIP by how long ago each job was released, and finished and on-time orders per week for twelve weeks. A percentage is null when there is nothing to measure it on. `mrp:view`.", "operationId": "getApiWorkOrdersKpis", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "How many days forward or back the window covers.", "schema": { "type": "integer" }, "example": "90" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "finished": { "type": "integer" }, "onTimePercent": { "type": "number" }, "outputVsPlanPercent": { "type": "number" }, "labourEfficiencyPercent": { "type": "number" }, "wipAgeing": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "jobs": { "type": "integer" }, "balance": { "type": "number" } } } }, "weeks": { "type": "array", "items": { "type": "object", "properties": { "weekStarting": { "type": "string", "format": "date" }, "finished": { "type": "integer" }, "onTime": { "type": "integer" } } } } } }, "example": { "from": "2026-07-01", "to": "2026-09-28", "finished": 31, "onTimePercent": 83.9, "outputVsPlanPercent": 97.2, "labourEfficiencyPercent": 91.5, "wipAgeing": [ { "label": "Under a week", "jobs": 4, "balance": 18250.0 } ], "weeks": [ { "weekStarting": "2026-09-21", "finished": 3, "onTime": 2 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/counts": { "get": { "tags": [ "Production & work orders" ], "summary": "How many work orders are in each status — the figures behind Production's tiles, unaffected by the list's filter or search.", "operationId": "getApiWorkOrdersCounts", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "planned": { "type": "integer" }, "released": { "type": "integer" }, "in_progress": { "type": "integer" }, "completed": { "type": "integer" }, "cancelled": { "type": "integer" } } }, "example": { "planned": 12, "released": 7, "in_progress": 3, "completed": 30, "cancelled": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/late": { "get": { "tags": [ "Production & work orders" ], "summary": "How many open work orders are past the day they are needed (the required date, else the planned finish) — Production's late figure and the dashboard's.", "operationId": "getApiWorkOrdersLate", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "type": "string", "format": "date" }, "count": { "type": "integer" } } }, "example": { "asOf": "2026-10-11", "count": 2 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/make-to-order": { "post": { "tags": [ "Production & work orders" ], "summary": "Make one item of a live quote or invoice to order. The work order is linked to the document, due on its delivery date, and planning stops counting that quantity as unmet demand. 409 when the document is a draft, already made to order, or the item has no recipe.", "operationId": "postApiWorkOrdersMakeToOrder", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string" }, "documentId": { "type": "string" }, "productId": { "type": "string" } } }, "example": { "variantId": "7d2e1a00-1111-4222-8333-944455556666", "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "7b2e4d10-8c3f-4a5e-b9d1-6f0a2c4e8b17" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWorkOrdersReworkResponse" }, "example": { "id": "9c4e1a27-3d5b-4f60-8e12-7a9b0c1d2e3f", "woNumber": "WO-0042" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Production & work orders" ], "summary": "The jobs making a quote or invoice to order, which of its items can be made (an active recipe), and why the document itself cannot be made to order, if it cannot.", "operationId": "getApiWorkOrdersMakeToOrder", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "documentId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "workOrderId": { "type": "string" }, "woNumber": { "type": "string" }, "status": { "type": "string" }, "qtyPlanned": { "type": "number" } } } }, "makeableProductIds": { "type": "array", "items": { "type": "string" } }, "refusal": { "type": "null" } } }, "example": { "jobs": [ { "productId": "7b2e4d10-8c3f-4a5e-b9d1-6f0a2c4e8b17", "workOrderId": "9c4e1a27-3d5b-4f60-8e12-7a9b0c1d2e3f", "woNumber": "WO-0042", "status": "planned", "qtyPlanned": 5.0 } ], "makeableProductIds": [ "7b2e4d10-8c3f-4a5e-b9d1-6f0a2c4e8b17" ], "refusal": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/make-to-order/waiting": { "get": { "tags": [ "Production & work orders" ], "summary": "The orders a customer has said yes to (an accepted quote, an open sales order, a draft invoice, a portal request) with an item made here and no open job making it — Material Planning's list for making to order. No money is on it.", "operationId": "getApiWorkOrdersMakeToOrderWaiting", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "documentId": { "type": "string" }, "documentNumber": { "type": "string" }, "documentType": { "type": "string" }, "status": { "type": "string" }, "customerName": { "type": "string" }, "wantedBy": { "type": "string", "format": "date" }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "type": "null" }, "description": { "type": "string" }, "qty": { "type": "number" } } } } } } }, "example": [ { "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "QUO-2026-006", "documentType": "quote", "status": "accepted", "customerName": "Mthembu Farms", "wantedBy": "2026-11-19", "items": [ { "productId": "7b2e4d10-8c3f-4a5e-b9d1-6f0a2c4e8b17", "variantId": null, "description": "Driveway gate 4m", "qty": 2.0 } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}": { "get": { "tags": [ "Production & work orders" ], "summary": "One work order with its material, labour and cost position.", "operationId": "getApiWorkOrdersById", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomName": "Karoo Fresh Holdings Ltd", "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "locationName": "Karoo Fresh Holdings Ltd", "qtyPlanned": 1.0, "qtyCompleted": 1.0, "status": "sent", "priority": 1, "plannedStart": "2026-09-01", "plannedFinish": "text", "actualStart": "2026-09-01", "actualFinish": "text", "estimatedCost": 10005.0, "actualCost": 10005.0, "assemblyBuildId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "mrpRunNumber": "INV-0001", "notes": "Budget deferred to the next financial year.", "shortages": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "required": 1.0, "onHand": 1.0, "short": 1.0 } ], "canStart": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Production & work orders" ], "summary": "Move an open work order: `plannedStart`, `plannedFinish`, `requiredDate` and `priority` (1 first, to 9). Each field left out is left alone. A released order's steps follow the new dates when they still carry the order's own dates; a step scheduled on its own keeps them. Refused on a completed or cancelled order, for a due date before the start, and for a date more than five years from today. `mrp:edit`.", "operationId": "putApiWorkOrdersById", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plannedStart": { "type": "string", "format": "date" }, "plannedFinish": { "type": "string", "format": "date" }, "priority": { "type": "integer" }, "requiredDate": { "type": "string", "format": "date" } } }, "example": { "plannedStart": "2026-10-05", "plannedFinish": "2026-10-09", "priority": 2, "requiredDate": "2026-09-12" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "stepsMoved": { "type": "string" } } }, "example": { "status": "rescheduled", "stepsMoved": "2" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/release": { "post": { "tags": [ "Production & work orders" ], "summary": "Release the order to the floor.", "operationId": "postApiWorkOrdersByIdRelease", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "operationsCreated": { "type": "integer" } } }, "example": { "status": "sent", "operationsCreated": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/reload-recipe": { "post": { "tags": [ "Production & work orders" ], "summary": "Re-pin an open job to the recipe in force now. A job fixes its components once, on purpose — a standard is what actuals are measured against, and re-reading it at completion compares actual against actual and reports a zero variance for ever — so an approved engineering change otherwise reaches only jobs released after it, and every job already open keeps building to the superseded drawing. This is that decision taken deliberately, and only while taking it is free: it is REFUSED once material has been issued, time has been booked or a unit has been completed, because re-pinning then would restate the baseline those actuals were already measured against. The refusal names which of the three it was. Optional `bomId` names the version to pin — checked to belong to this job's product — and omitting it means whichever recipe is in force. The job's route is deliberately untouched. `mrp:edit`.", "operationId": "postApiWorkOrdersByIdReloadRecipe", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workOrderId": { "type": "string" }, "bomId": { "type": "string" }, "bomVersion": { "type": "string" }, "changed": { "type": "boolean" }, "previousLines": { "type": "integer" }, "lines": { "type": "integer" }, "previousMaterialPerUnit": { "type": "number" }, "materialPerUnit": { "type": "number" }, "standardRepinned": { "type": "boolean" } } }, "example": { "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomVersion": "1", "changed": false, "previousLines": 1, "lines": 1, "previousMaterialPerUnit": 1.0, "materialPerUnit": 1.0, "standardRepinned": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/cancel": { "post": { "tags": [ "Production & work orders" ], "summary": "Cancel an order and return what it holds.", "operationId": "postApiWorkOrdersByIdCancel", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "wipWrittenOff": { "type": "string" } } }, "example": { "status": "sent", "wipWrittenOff": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/complete": { "post": { "tags": [ "Production & work orders" ], "summary": "Complete the order. closeJob stays a wire name — the screen says \"work order\" everywhere, but renaming the field would break the contract.", "operationId": "postApiWorkOrdersByIdComplete", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lotNumber": { "type": "string" }, "expiryDate": { "type": "string", "format": "date" }, "qtyCompleted": { "type": "number" }, "qtyScrapped": { "type": "number" }, "locationId": { "type": "string" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "backflush": { "type": "boolean" }, "closeJob": { "type": "boolean" }, "serials": { "type": "array", "items": { "type": "object" } }, "clientId": { "type": "string" } } }, "example": { "lotNumber": "L26-0412", "expiryDate": "2026-12-30", "qtyCompleted": 248.0, "qtyScrapped": 2.0, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "backflush": true, "closeJob": true, "serials": [], "clientId": "8d2f5a61-3c7e-4b90-a1d4-6e9b2c0f7a15" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "completionId": { "type": "string" }, "qtyCompleted": { "type": "number" }, "standardUnitCost": { "type": "number" }, "standardTotal": { "type": "number" }, "completionJournalId": { "type": "string" }, "varianceJournalId": { "type": "string" }, "wipBalance": { "type": "number" }, "isFinal": { "type": "boolean" }, "totalVariance": { "type": "number" }, "variances": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdCostingResponseVariancesItem" } }, "backflushed": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiWorkOrdersByIdIssueResponseLinesItem" } }, "shortComponents": { "type": "array", "items": { "type": "string" } }, "incompleteOperations": { "type": "array", "items": { "type": "string" } } } }, "example": { "status": "sent", "completionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyCompleted": 1.0, "standardUnitCost": 2900.0, "standardTotal": 10005.0, "completionJournalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "varianceJournalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "wipBalance": 10005.0, "isFinal": false, "totalVariance": 10005.0, "variances": [ { "type": "standard", "label": "Karoo Fresh Holdings Ltd", "amount": 10005.0, "accountCode": "CT-001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "standardQty": 3.0, "actualQty": 3.0, "standardRate": 15.0, "actualRate": 15.0, "explanation": "text", "favourable": false, "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "backflushed": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "qty": 3.0, "actualUnitCost": 2900.0, "actualTotalCost": 10005.0, "standardUnitCost": 2900.0, "short": false, "issueType": "standard", "issuedAt": "2026-09-01T09:15:00Z", "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "shortComponents": [ "text" ], "incompleteOperations": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/completions/{id}/reverse": { "post": { "tags": [ "Production & work orders" ], "summary": "Reverse a completion. Withdraws the units actually moved, not the quantity requested — the reversal path carried the same rounding defect mirrored.", "operationId": "postApiWorkOrdersCompletionsByIdReverse", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "qty": { "type": "number" }, "reason": { "type": "string" } } }, "example": { "qty": 2.0, "reason": "Booked against the wrong work order" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "reversalId": { "type": "string" }, "qtyReversed": { "type": "number" }, "standardTotal": { "type": "number" }, "journalId": { "type": "string" }, "varianceJournalReversedId": { "type": "string" }, "jobReopened": { "type": "boolean" }, "wipBalance": { "type": "number" } } }, "example": { "reversalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyReversed": 1.0, "standardTotal": 10005.0, "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "varianceJournalReversedId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobReopened": false, "wipBalance": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/issuable": { "get": { "tags": [ "Production & work orders" ], "summary": "What can be issued to this job, or returned from it: its recipe items and everything it already holds, plus — with `q` — any stock item whose name or code matches. Each with what is on the shelf and what the job holds, which is the most a return may give back. `mrp:view`.", "operationId": "getApiWorkOrdersByIdIssuable", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "bracket" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "onHand": { "type": "number" }, "issued": { "type": "number" }, "onRecipe": { "type": "boolean" } } } } } }, "example": { "items": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "FB-40x5", "name": "Flat bar 40x5", "unit": "m", "onHand": 120.0, "issued": 20.0, "onRecipe": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/document": { "get": { "tags": [ "Production & work orders" ], "summary": "The work order on paper — `format=pdf` (the default) or `format=html`: the job and its dates, a QR code for the order, every step of its route with the operator's instructions, a QR code for the step and boxes to sign it off, and the pick list — needed, issued, still to pick. The codes are the ones the Production scanner reads. `mrp:view`.", "operationId": "getApiWorkOrdersByIdDocument", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "pdf" } ], "responses": { "200": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/labels": { "get": { "tags": [ "Production & work orders" ], "summary": "Labels for what the job made, 100 × 60 mm, one a page: one per completion with the product, its lot, the quantity, the date and a QR code the scanner reads as that lot — or, before anything is made, one for the order. `completionId` narrows to one completion. A product with a GTIN also gets a GS1-128 a retailer's dock scans, on an A6 label (T-M2.4): `kind=lot` (the default) carries (01) GTIN-14, (17) expiry and (10) lot; `kind=case&count=` adds (37) the count with (02); `kind=pallet&count=` adds a second symbol, (00) an SSCC from the company's GS1 prefix, new for every copy and never repeated. `copies=` 1–100 of each. A case or pallet label is refused (409) for a product with no GTIN, and a pallet label for a company with no prefix. `mrp:view`.", "operationId": "getApiWorkOrdersByIdLabels", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "required": false, "description": "What to answer with. `json` always answers, carrying the figures and any issues; a FILE format answers 422 with the reasons when the document does not validate, so a wrong file is never emitted.", "schema": { "type": "string" }, "example": "pdf" }, { "name": "completionId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "example": "case" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "24" }, { "name": "copies", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" } ], "responses": { "200": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/issue": { "post": { "tags": [ "Production & work orders" ], "summary": "Issue material. With no lines, issues the recipe's requirement for the outstanding quantity, which is what a storeman picking a whole job wants. Negative quantities return material at the price the job was charged.", "operationId": "postApiWorkOrdersByIdIssue", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowAlternates": { "type": "boolean" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "qty": { "type": "number" }, "variantId": { "type": "string" } } } }, "qtyForUnits": { "type": "number" }, "locationId": { "type": "string" }, "reference": { "type": "string" }, "notes": { "type": "string" }, "serials": { "$ref": "#/components/schemas/PostApiInvoicesRequestCustomFields" }, "clientId": { "type": "string" } } }, "example": { "allowAlternates": false, "lines": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qty": 3.0, "variantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "qtyForUnits": 1.0, "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "notes": "Budget deferred to the next financial year.", "serials": {}, "clientId": "8d2f5a61-3c7e-4b90-a1d4-6e9b2c0f7a15" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiWorkOrdersByIdIssueResponseLinesItem" } }, "totalCost": { "type": "number" }, "journalId": { "type": "string" }, "wipBalance": { "type": "number" }, "shortComponents": { "type": "array", "items": { "type": "string" } } } }, "example": { "lines": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "qty": 3.0, "actualUnitCost": 2900.0, "actualTotalCost": 10005.0, "standardUnitCost": 2900.0, "short": false, "issueType": "standard", "issuedAt": "2026-09-01T09:15:00Z", "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "totalCost": 10005.0, "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "wipBalance": 10005.0, "shortComponents": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/labour": { "post": { "tags": [ "Production & work orders" ], "summary": "Book hours against the order.", "operationId": "postApiWorkOrdersByIdLabour", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hours": { "type": "number" }, "rate": { "type": "number" }, "overheadRate": { "type": "number" }, "operationId": { "type": "string" }, "workCentreId": { "type": "string" }, "employeeId": { "type": "string" }, "entryDate": { "type": "string", "format": "date" }, "notes": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "hours": 6.0, "rate": 15.0, "overheadRate": 15.0, "operationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "entryDate": "2026-09-01", "notes": "Budget deferred to the next financial year.", "clientId": "8d2f5a61-3c7e-4b90-a1d4-6e9b2c0f7a15" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "labourCost": { "type": "string" }, "overheadCost": { "type": "string" }, "journalId": { "type": "string" }, "wipBalance": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "labourCost": "text", "overheadCost": "text", "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "wipBalance": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/costing": { "get": { "tags": [ "Production & work orders" ], "summary": "The order's costing view — material, labour, overhead and the variances against standard.", "operationId": "getApiWorkOrdersByIdCosting", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdCostingResponse" }, "example": { "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "status": "sent", "qtyPlanned": 1.0, "qtyCompleted": 1.0, "qtyScrapped": 1.0, "stdMaterialPerUnit": 1.0, "stdLabourPerUnit": 1.0, "stdOverheadPerUnit": 1.0, "stdTotalPerUnit": 10005.0, "stdHoursPerUnit": 3.0, "stdLabourRate": 15.0, "standardCostOfOutput": 10005.0, "actualMaterial": 1.0, "actualLabour": 1.0, "actualOverhead": 1.0, "actualTotal": 10005.0, "actualHours": 3.0, "wipRelieved": 1.0, "wipVarianceCleared": 1.0, "wipBalance": 10005.0, "totalVariance": 10005.0, "variances": [ { "type": "standard", "label": "Karoo Fresh Holdings Ltd", "amount": 10005.0, "accountCode": "CT-001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "standardQty": 3.0, "actualQty": 3.0, "standardRate": 15.0, "actualRate": 15.0, "explanation": "text", "favourable": false, "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "issues": [], "labour": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hours": 3.0, "actualRate": 15.0, "actualCost": 10005.0, "standardRate": 15.0, "overheadCost": 10005.0, "entryType": "standard", "entryDate": "2026-09-01", "employeeName": "Thandi Mokoena", "notes": "Budget deferred to the next financial year.", "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "hasRouting": false, "standardPinned": false, "completions": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyCompleted": 1.0, "qtyScrapped": 1.0, "standardUnitCost": 2900.0, "standardTotal": 10005.0, "isFinal": false, "completedAt": "2026-09-01T09:15:00Z", "completedByName": "Karoo Fresh Holdings Ltd", "reference": "INV-0001", "reversedAt": "2026-09-01T09:15:00Z", "reversalOfId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reversalReason": "Budget deferred to the next financial year.", "qtyStillInStock": 1.0, "canReverse": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/schedule": { "get": { "tags": [ "Production & work orders" ], "summary": "Every open work order laid onto the hours its work centres actually have, after each centre's queue days, forward from today in priority order — or, with `?direction=backward`, back from each job's due date so it starts as late as still finishes on time (a job with no due date, or one that cannot fit, is laid forward): each job's proposed start and finish, whether that changes its planned dates, how late it will be against the date it is needed by, and each operation's dates at its centre. A proposal — nothing is moved.", "operationId": "getApiWorkOrdersSchedule", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "type": "string" }, "example": "backward" }, { "name": "siteId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "5a714b17-9c3a-4f60-b5d1-7e0a2c9f4b86" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "today": { "type": "string" }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "workOrderId": { "type": "string" }, "woNumber": { "type": "string" }, "productName": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "integer" }, "plannedStart": { "type": "string", "format": "date" }, "plannedFinish": { "type": "string" }, "scheduledStart": { "type": "string", "format": "date" }, "scheduledFinish": { "type": "string" }, "requiredDate": { "type": "string", "format": "date" }, "daysLate": { "type": "integer" }, "cannotPlace": { "type": "string" }, "changes": { "type": "boolean" } } } }, "operations": { "type": "array", "items": { "type": "object", "properties": { "workOrderId": { "type": "string" }, "woNumber": { "type": "string" }, "operationId": { "type": "string" }, "sequenceNo": { "type": "integer" }, "description": { "type": "string" }, "workCentreId": { "type": "string" }, "workCentreName": { "type": "string" }, "hours": { "type": "number" }, "start": { "type": "string", "format": "date" }, "finish": { "type": "string" }, "subcontract": { "type": "boolean" } } } }, "lateCount": { "type": "integer" }, "changeCount": { "type": "integer" }, "cannotPlaceCount": { "type": "integer" } } }, "example": { "today": "text", "jobs": [ { "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "productName": "Karoo Fresh Holdings Ltd", "status": "sent", "priority": 1, "plannedStart": "2026-09-01", "plannedFinish": "text", "scheduledStart": "2026-09-01", "scheduledFinish": "text", "requiredDate": "2026-09-01", "daysLate": 30, "cannotPlace": "text", "changes": true } ], "operations": [ { "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "operationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sequenceNo": 1, "description": "Consulting services — August 2026", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workCentreName": "Karoo Fresh Holdings Ltd", "hours": 3.0, "start": "2026-09-01", "finish": "text", "subcontract": true } ], "lateCount": 3, "changeCount": 3, "cannotPlaceCount": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/schedule/apply": { "post": { "tags": [ "Production & work orders" ], "summary": "Apply the reviewed schedule: every job it moves gets the proposed planned start and finish (the date it was needed by is kept), and a released job's operations their scheduled dates. The body lists the dates reviewed; when the schedule worked out now differs, nothing is written and 409 is returned.", "operationId": "postApiWorkOrdersScheduleApply", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "updatedJobs": { "type": "integer" }, "updatedOperations": { "type": "integer" } } }, "example": { "updatedJobs": 1, "updatedOperations": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/operations": { "get": { "tags": [ "Production & work orders" ], "summary": "The order's operations and their state.", "operationId": "getApiWorkOrdersByIdOperations", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdOperationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Production & work orders" ], "summary": "Attach operations to the order, usually copied from the routing.", "operationId": "postApiWorkOrdersByIdOperations", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sequenceNo": { "type": "integer" }, "description": { "type": "string" }, "workCentreId": { "type": "string" }, "setupHours": { "type": "number" }, "runHoursPerUnit": { "type": "number" }, "isSubcontract": { "type": "boolean" }, "subcontractCostPerUnit": { "type": "number" }, "notes": { "type": "string" }, "instructions": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "sequenceNo": 1, "description": "Consulting services — August 2026", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "setupHours": 3.0, "runHoursPerUnit": 3.0, "isSubcontract": false, "subcontractCostPerUnit": 10005.0, "notes": "Budget deferred to the next financial year.", "instructions": "Deburr both ends before the bend.", "clientId": "8d2f5a61-3c7e-4b90-a1d4-6e9b2c0f7a15" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdOperationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/start": { "post": { "tags": [ "Production & work orders" ], "summary": "Start an operation.", "operationId": "postApiWorkOrdersOperationsByOpIdStart", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdOperationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/book": { "post": { "tags": [ "Production & work orders" ], "summary": "Book time and quantity against an operation.", "operationId": "postApiWorkOrdersOperationsByOpIdBook", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hours": { "type": "number" }, "qtyCompleted": { "type": "number" }, "qtyScrapped": { "type": "number" }, "scrapReasonCode": { "type": "string" }, "scrapNotes": { "type": "string" }, "complete": { "type": "boolean" }, "notes": { "type": "string" }, "clientId": { "type": "string" }, "workerId": { "type": "string" } } }, "example": { "hours": 2.5, "qtyCompleted": 60.0, "qtyScrapped": 1.0, "scrapReasonCode": "CT-001", "scrapNotes": "Budget deferred to the next financial year.", "complete": true, "notes": "Budget deferred to the next financial year.", "clientId": "8d2f5a61-3c7e-4b90-a1d4-6e9b2c0f7a15", "workerId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdOperationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}": { "get": { "tags": [ "Production & work orders" ], "summary": "The order a step belongs to, with its progress — what scanning a step's code on the traveller opens. `mrp:view`; another company's step is not found.", "operationId": "getApiWorkOrdersOperationsByOpId", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdOperationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Production & work orders" ], "summary": "Change a released order's step: its description, work centre, this job's planned setup and run hours, the operator's instructions and notes. Each field left out is left alone; the route is not touched. Moving the step to another centre re-freezes the rates from that centre, and is refused once hours are booked at the old ones. A skipped or closed step is refused. Answers the order's progress. `mrp:edit`.", "operationId": "putApiWorkOrdersOperationsByOpId", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plannedRunHours": { "type": "number" }, "instructions": { "type": "string" }, "description": { "type": "string" }, "workCentreId": { "type": "string" }, "plannedSetupHours": { "type": "number" }, "notes": { "type": "string" }, "scheduledStart": { "type": "string", "format": "date" }, "scheduledFinish": { "type": "string", "format": "date" } } }, "example": { "plannedRunHours": 6.5, "instructions": "Tack all four corners before the long seams.", "description": "Weld chassis", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "plannedSetupHours": 0.5, "notes": "Jig changed to the new fixture.", "scheduledStart": "2026-09-02", "scheduledFinish": "2026-09-03" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdOperationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/subcontract-order": { "post": { "tags": [ "Production & work orders" ], "summary": "Order an outsourced step from its subcontractor: a draft purchase order for the units still to send. Receiving it books the step (DR 1315 / CR 5067) and the supplier's bill clears 5067.", "operationId": "postApiWorkOrdersOperationsByOpIdSubcontractOrder", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplierId": { "type": "string" }, "qty": { "type": "number" }, "unitCost": { "type": "number" }, "expectedDate": { "type": "string", "format": "date" } } }, "example": { "supplierId": "bc1d8fe0-3c9e-5d4a-b109-3998299318d9", "qty": 10.0, "unitCost": 90.0, "expectedDate": "2026-10-07" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdSubcontractOrdersResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdSubcontractOrdersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/work-centres/{id}/signals": { "post": { "tags": [ "Production & work orders" ], "summary": "A machine's own signals: running, stopped or fault, with the device's sequence number and the good and reject parts it counted. A stop that lasts the work centre's threshold (2 minutes unless set) becomes a downtime event with no reason yet, closed by the next running; a shorter one is a micro-stop. A sequence number already taken changes nothing. A key scoped to machine-signals:write may post only for the work centres it names and can read nothing. At most 500 signals a post.", "operationId": "postApiMrpWorkCentresByIdSignals", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signals": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer" }, "kind": { "type": "string" }, "at": { "type": "string" }, "good": { "type": "integer" }, "reject": { "type": "integer" } } } } } }, "example": { "signals": [ { "seq": 1042, "kind": "stopped", "at": "2026-10-12T10:15:00+02:00", "good": 120, "reject": 2 } ] } } } }, "responses": { "201": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/downtime/{eventId}/reason": { "post": { "tags": [ "Production & work orders" ], "summary": "Say why a machine stopped: the reason on a stop, typically one the machine recorded with no reason yet.", "operationId": "postApiMrpDowntimeByEventIdReason", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "notes": { "type": "string" } } }, "example": { "reason": "changeover", "notes": "Die change for the next job" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdRejectRequest" }, "example": { "reason": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/work-centres/{id}/maintenance": { "get": { "tags": [ "Production & work orders" ], "summary": "A machine's preventive maintenance plans: each with its hours run or units processed since the last service, whether it is due, and the job card booked for it.", "operationId": "getApiMrpWorkCentresByIdMaintenance", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpWorkCentresByIdMaintenanceResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workCentreName": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "title": "Karoo Fresh Holdings Ltd", "trigger": "hours", "cycle": 1.0, "cadence": "text", "downtimeHours": 3.0, "lastServiceAt": "2026-09-01T09:15:00Z", "meter": 1.0, "due": false, "nextDueOn": "2026-09-01", "standing": "text", "openJobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "openJobNumber": "JC-0001", "openScheduledStart": "2026-09-01", "active": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Production & work orders" ], "summary": "A maintenance plan for the machine: a job card for whoever services it when the hours run (or units processed) since the last service reach the cycle, or on a calendar cadence. The card's scheduled hours come off the centre's capacity. Needs Job Cards on the plan.", "operationId": "postApiMrpWorkCentresByIdMaintenance", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "title": { "type": "string" }, "trigger": { "type": "string" }, "cycle": { "type": "number" }, "cadence": { "type": "string" }, "downtimeHours": { "type": "number" }, "lastServiceOn": { "type": "string", "format": "date" } } }, "example": { "contactId": "bc1d8fe0-3c9e-5d4a-b109-3998299318d9", "title": "500-hour service", "trigger": "hours", "cycle": 500.0, "cadence": "quarterly", "downtimeHours": 8.0, "lastServiceOn": "2026-10-01" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpWorkCentresByIdMaintenanceResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "workCentreName": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "title": "Karoo Fresh Holdings Ltd", "trigger": "hours", "cycle": 1.0, "cadence": "text", "downtimeHours": 3.0, "lastServiceAt": "2026-09-01T09:15:00Z", "meter": 1.0, "due": false, "nextDueOn": "2026-09-01", "standing": "text", "openJobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "openJobNumber": "JC-0001", "openScheduledStart": "2026-09-01", "active": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/maintenance-plans/{planId}": { "delete": { "tags": [ "Production & work orders" ], "summary": "Stop planning a machine's service. Cards already raised stay.", "operationId": "deleteApiMrpMaintenancePlansByPlanId", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mrp/maintenance/check": { "post": { "tags": [ "Production & work orders" ], "summary": "Raise every due maintenance plan's job card now rather than at the overnight run. A plan with a card still open raises nothing.", "operationId": "postApiMrpMaintenanceCheck", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "raised": { "type": "array", "items": { "type": "string" } } } }, "example": { "raised": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/free-issue": { "get": { "tags": [ "Production & work orders" ], "summary": "The material sent with an outsourced step, and where each part stands: sent, consumed by the subcontractor's returns, brought back, and still at their location. It stays the business's stock (1310) throughout.", "operationId": "getApiWorkOrdersOperationsByOpIdFreeIssue", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersOperationsByOpIdFreeIssueResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersOperationsByOpIdFreeIssueResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Production & work orders" ], "summary": "Send material with an outsourced step: a confirmed transfer to the subcontractor's own stock location, which posts nothing. Their return then consumes the job's recipe share from that location into WIP.", "operationId": "postApiWorkOrdersOperationsByOpIdFreeIssue", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "qty": { "type": "number" } } } } } }, "example": { "lines": [ { "productId": "bc1d8fe0-3c9e-5d4a-b109-3998299318d9", "qty": 100.0 } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersOperationsByOpIdFreeIssueResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersOperationsByOpIdFreeIssueResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/free-issue/return": { "post": { "tags": [ "Production & work orders" ], "summary": "Bring back what is still at the subcontractor for the step: a transfer home that posts nothing. 409 when nothing is left there.", "operationId": "postApiWorkOrdersOperationsByOpIdFreeIssueReturn", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersOperationsByOpIdFreeIssueResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersOperationsByOpIdFreeIssueResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/{id}/subcontract-orders": { "get": { "tags": [ "Production & work orders" ], "summary": "The purchase orders buying this work order's outsourced steps — raised on the step or from Material Planning.", "operationId": "getApiWorkOrdersByIdSubcontractOrders", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdSubcontractOrdersResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdSubcontractOrdersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/complete": { "post": { "tags": [ "Production & work orders" ], "summary": "Complete an operation.", "operationId": "postApiWorkOrdersOperationsByOpIdComplete", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdOperationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/clock-on": { "post": { "tags": [ "Production & work orders" ], "summary": "Start the clock on a step, for yourself or `workerId`, on the server's clock. Several people may be on one step, each once; the step starts if it had not. Refused on a closed or skipped step. Answers the order's progress, each step listing who is clocked on and since when. `mrp:edit`.", "operationId": "postApiWorkOrdersOperationsByOpIdClockOn", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workerId": { "type": "string" } } }, "example": { "workerId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdOperationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/clock-off": { "post": { "tags": [ "Production & work orders" ], "summary": "Stop the clock and book its hours through the ordinary step booking, so cost and WIP post exactly as a typed booking would. `finish` closes the step with `qtyCompleted` and any scrap — refused while someone else is still clocked on. A clock that ran past a double shift asks for `hours`, what was really worked. `clientId` makes a retry land once. `mrp:edit`.", "operationId": "postApiWorkOrdersOperationsByOpIdClockOff", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "finish": { "type": "boolean" }, "qtyCompleted": { "type": "integer" }, "workerId": { "type": "string" }, "hours": { "type": "number" }, "qtyScrapped": { "type": "number" }, "scrapReasonCode": { "type": "null" }, "notes": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "finish": true, "qtyCompleted": 4, "workerId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hours": 1.5, "qtyScrapped": 0.0, "scrapReasonCode": null, "notes": "Stopped for the shift change.", "clientId": "8d2f5a61-3c7e-4b90-a1d4-6e9b2c0f7a15" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdOperationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/skip": { "post": { "tags": [ "Production & work orders" ], "summary": "Skip a step this job does not need, with `reason` (required, up to 300 characters). Only a step nobody has touched: once hours or units are booked it is closed, not skipped. A skipped step leaves the capacity load and the schedule, and keeps its reason on the job. Answers the order's progress. `mrp:edit`.", "operationId": "postApiWorkOrdersOperationsByOpIdSkip", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdRejectRequest" }, "example": { "reason": "Customer collects it unpainted" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdOperationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-orders/operations/{opId}/restore": { "post": { "tags": [ "Production & work orders" ], "summary": "Put a skipped step back to pending, clearing its reason. Answers the order's progress. `mrp:edit`.", "operationId": "postApiWorkOrdersOperationsByOpIdRestore", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "opId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdOperationsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiWorkOrdersByIdOperationsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/work-in-progress": { "get": { "tags": [ "Production & work orders" ], "summary": "The open WIP balance by job. This is what reconciles the WIP control account to the floor. jobs and openJobCount stay wire names.", "operationId": "getApiWorkInProgress", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalWip": { "type": "number" }, "openJobCount": { "type": "integer" }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiWorkOrdersByIdCostingResponse" } }, "ledgerWip": { "type": "number" }, "controlDifference": { "type": "number" } } }, "example": { "totalWip": 10005.0, "openJobCount": 3, "jobs": [ { "workOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "woNumber": "INV-0001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "status": "sent", "qtyPlanned": 1.0, "qtyCompleted": 1.0, "qtyScrapped": 1.0, "stdMaterialPerUnit": 1.0, "stdLabourPerUnit": 1.0, "stdOverheadPerUnit": 1.0, "stdTotalPerUnit": 10005.0, "stdHoursPerUnit": 3.0, "stdLabourRate": 15.0, "standardCostOfOutput": 10005.0, "actualMaterial": 1.0, "actualLabour": 1.0, "actualOverhead": 1.0, "actualTotal": 10005.0, "actualHours": 3.0, "wipRelieved": 1.0, "wipVarianceCleared": 1.0, "wipBalance": 10005.0, "totalVariance": 10005.0, "variances": [ { "type": "standard", "label": "Karoo Fresh Holdings Ltd", "amount": 10005.0, "accountCode": "CT-001", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "standardQty": 3.0, "actualQty": 3.0, "standardRate": 15.0, "actualRate": 15.0, "explanation": "text", "favourable": false, "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "issues": [], "labour": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hours": 3.0, "actualRate": 15.0, "actualCost": 10005.0, "standardRate": 15.0, "overheadCost": 10005.0, "entryType": "standard", "entryDate": "2026-09-01", "employeeName": "Thandi Mokoena", "notes": "Budget deferred to the next financial year.", "journalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "hasRouting": false, "standardPinned": false, "completions": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyCompleted": 1.0, "qtyScrapped": 1.0, "standardUnitCost": 2900.0, "standardTotal": 10005.0, "isFinal": false, "completedAt": "2026-09-01T09:15:00Z", "completedByName": "Karoo Fresh Holdings Ltd", "reference": "INV-0001", "reversedAt": "2026-09-01T09:15:00Z", "reversalOfId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reversalReason": "Budget deferred to the next financial year.", "qtyStillInStock": 1.0, "canReverse": false } ] } ], "ledgerWip": 1.0, "controlDifference": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/standard-costs": { "get": { "tags": [ "Production & work orders" ], "summary": "Stored standard-cost results.", "operationId": "getApiStandardCosts", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Production & work orders" ], "summary": "Override a standard cost by hand.", "operationId": "putApiStandardCosts", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "materialCost": { "type": "number" }, "labourCost": { "type": "number" }, "overheadCost": { "type": "number" }, "labourHoursPerUnit": { "type": "number" }, "notes": { "type": "string" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "materialCost": 1284.5, "labourCost": 10005.0, "overheadCost": 10005.0, "labourHoursPerUnit": 3.0, "notes": "Budget deferred to the next financial year." } } } }, "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/standard-costs/roll-up": { "post": { "tags": [ "Production & work orders" ], "summary": "Roll the BOM cost up through every level and store the result.", "operationId": "postApiStandardCostsRollUp", "description": "Requires the `mrp:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productIds": { "type": "array", "items": { "type": "string" } } } }, "example": { "productIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "computed": { "type": "integer" }, "unchanged": { "type": "integer" }, "standards": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiStandardCostsByProductIdResponseItem" } }, "cycles": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "warnings": { "type": "array", "items": { "type": "object" } }, "routingsAvailable": { "type": "boolean" } } }, "example": { "computed": 1, "unchanged": 1, "standards": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomName": "Karoo Fresh Holdings Ltd", "materialCost": 10005.0, "labourCost": 10005.0, "overheadCost": 10005.0, "totalCost": 10005.0, "labourHoursPerUnit": 3.0, "labourRate": 15.0, "costSource": "referral", "bomLevel": 1, "version": 1, "effectiveFrom": "2026-09-01", "notes": "Budget deferred to the next financial year." } ], "cycles": [ [ "text" ] ], "warnings": [], "routingsAvailable": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/standard-costs/{productId}": { "get": { "tags": [ "Production & work orders" ], "summary": "One product's standard cost and how it was arrived at.", "operationId": "getApiStandardCostsByProductId", "description": "Requires the `mrp:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "mrp:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiStandardCostsByProductIdResponseItem" } }, "example": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "bomId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bomName": "Karoo Fresh Holdings Ltd", "materialCost": 10005.0, "labourCost": 10005.0, "overheadCost": 10005.0, "totalCost": 10005.0, "labourHoursPerUnit": 3.0, "labourRate": 15.0, "costSource": "bom_rollup", "bomLevel": 1, "version": 1, "effectiveFrom": "2026-09-01", "notes": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/overview": { "get": { "tags": [ "Procurement" ], "summary": "The buyer's dashboard — open requisitions, orders awaiting approval and unmatched receipts.", "operationId": "getApiProcurementOverview", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "openRequisitionCount": { "type": "integer" }, "awaitingApprovalCount": { "type": "integer" }, "awaitingMyApprovalCount": { "type": "integer" }, "requisitionValue": { "type": "number" }, "openRfqCount": { "type": "integer" }, "openPoCount": { "type": "integer" }, "openCommitmentValue": { "type": "number" }, "pendingDeliveryCount": { "type": "integer" }, "overdueDeliveryCount": { "type": "integer" }, "overdueDeliveryValue": { "type": "number" }, "onTimeDeliveryPercent": { "type": "number" }, "matchExceptionCount": { "type": "integer" }, "activeContractCount": { "type": "integer" }, "contractsExpiringCount": { "type": "integer" }, "approvedVendorCount": { "type": "integer" }, "blockedVendorCount": { "type": "integer" }, "productsWithoutVendorCount": { "type": "integer" } } }, "example": { "openRequisitionCount": 3, "awaitingApprovalCount": 3, "awaitingMyApprovalCount": 3, "requisitionValue": 10005.0, "openRfqCount": 3, "openPoCount": 3, "openCommitmentValue": 10005.0, "pendingDeliveryCount": 3, "overdueDeliveryCount": 3, "overdueDeliveryValue": 10005.0, "onTimeDeliveryPercent": 15.0, "matchExceptionCount": 3, "activeContractCount": 3, "contractsExpiringCount": 3, "approvedVendorCount": 3, "blockedVendorCount": 3, "productsWithoutVendorCount": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/requisitions": { "get": { "tags": [ "Procurement" ], "summary": "Requisitions, newest first. `q` searches the number and title; `offset` and `limit` (default 100, at most 500) page through them — the count is at /requisitions/count.", "operationId": "getApiProcurementRequisitions", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "submitted" }, { "name": "awaitingMe", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" }, { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "PR-0001" }, { "name": "offset", "in": "query", "required": false, "description": "How many rows to skip. Use with `limit` to page. A paged response reports `total`, which is the number of rows matching the filter rather than the number returned.", "schema": { "type": "integer" }, "example": "0" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementRequisitionsByIdResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "requisitionNumber": "INV-0001", "title": "Karoo Fresh Holdings Ltd", "status": "sent", "priority": "normal", "requestedByName": "Karoo Fresh Holdings Ltd", "requestedFor": "text", "requiredDate": "2026-09-01", "currency": "ZAR", "estimatedTotal": 10005.0, "budgetAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "budgetAccountName": "Karoo Fresh Holdings Ltd", "budgetRemaining": 1.0, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreName": "Karoo Fresh Holdings Ltd", "mrpRunId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "mrpRunNumber": "INV-0001", "justification": "text", "notes": "Budget deferred to the next financial year.", "lineCount": 3, "submittedAt": "2026-09-01T09:15:00Z", "approvedAt": "2026-09-01T09:15:00Z", "rejectedAt": "2026-09-01T09:15:00Z", "rejectionReason": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "description": "Consulting services — August 2026", "qty": 3.0, "unit": "each", "requiredDate": "2026-09-01", "estimatedUnitPrice": 2900.0, "estimatedTotal": 10005.0, "suggestedSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "suggestedSupplierName": "Karoo Fresh Holdings Ltd", "plannedOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "sent", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "notes": "Budget deferred to the next financial year.", "approvedVendorCount": 3 } ], "approvals": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stepNo": 1, "approverLabel": "Thandi Mokoena", "approverRoleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "approverUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "sent", "decidedByName": "Thandi Mokoena", "decidedAt": "2026-09-01T09:15:00Z", "comment": "Budget deferred to the next financial year.", "canDecide": false } ], "currentStep": 1, "awaitingMe": false, "purchaseOrderIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Procurement" ], "summary": "Raise a requisition.", "operationId": "postApiProcurementRequisitions", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "title": { "type": "string" }, "priority": { "type": "string" }, "requestedFor": { "type": "string", "format": "date" }, "requiredDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "budgetAccountId": { "type": "string" }, "costCentreId": { "type": "string" }, "justification": { "type": "string" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "description": { "type": "string" }, "qty": { "type": "number" }, "unit": { "type": "string" }, "requiredDate": { "type": "string", "format": "date" }, "estimatedUnitPrice": { "type": "number" }, "suggestedSupplierId": { "type": "string" }, "notes": { "type": "string" } } } } } }, "example": { "clientId": "ec4ecf4b-712e-5979-806d-127d1b370ec8", "title": "Karoo Fresh Holdings Ltd", "priority": "normal", "requestedFor": "2026-10-15", "requiredDate": "2026-09-10", "currency": "ZAR", "budgetAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "justification": "Stock for the October production run", "notes": "Budget deferred to the next financial year.", "lines": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0, "unit": "each", "requiredDate": "2026-09-01", "estimatedUnitPrice": 84.5, "suggestedSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year." } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpForecastsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/requisitions/count": { "get": { "tags": [ "Procurement" ], "summary": "How many requisitions the list would page through for the same status and search — the figure behind 'Showing 100 of 106'.", "operationId": "getApiProcurementRequisitionsCount", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "submitted" }, { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "gas" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiExpensesCountResponse" }, "example": { "total": 106 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/requisitions/{id}": { "get": { "tags": [ "Procurement" ], "summary": "One requisition and its approval trail.", "operationId": "getApiProcurementRequisitionsById", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiProcurementRequisitionsByIdResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "requisitionNumber": "INV-0001", "title": "Karoo Fresh Holdings Ltd", "status": "sent", "priority": "normal", "requestedByName": "Karoo Fresh Holdings Ltd", "requestedFor": "text", "requiredDate": "2026-09-01", "currency": "ZAR", "estimatedTotal": 10005.0, "budgetAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "budgetAccountName": "Karoo Fresh Holdings Ltd", "budgetRemaining": 1.0, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreName": "Karoo Fresh Holdings Ltd", "mrpRunId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "mrpRunNumber": "INV-0001", "justification": "text", "notes": "Budget deferred to the next financial year.", "lineCount": 3, "submittedAt": "2026-09-01T09:15:00Z", "approvedAt": "2026-09-01T09:15:00Z", "rejectedAt": "2026-09-01T09:15:00Z", "rejectionReason": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "description": "Consulting services — August 2026", "qty": 3.0, "unit": "each", "requiredDate": "2026-09-01", "estimatedUnitPrice": 2900.0, "estimatedTotal": 10005.0, "suggestedSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "suggestedSupplierName": "Karoo Fresh Holdings Ltd", "plannedOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "sent", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "notes": "Budget deferred to the next financial year.", "approvedVendorCount": 3 } ], "approvals": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stepNo": 1, "approverLabel": "Thandi Mokoena", "approverRoleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "approverUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "sent", "decidedByName": "Thandi Mokoena", "decidedAt": "2026-09-01T09:15:00Z", "comment": "Budget deferred to the next financial year.", "canDecide": false } ], "currentStep": 1, "awaitingMe": false, "purchaseOrderIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/requisitions/{id}/submit": { "post": { "tags": [ "Procurement" ], "summary": "Submit for approval.", "operationId": "postApiProcurementRequisitionsByIdSubmit", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/requisitions/{id}/approve": { "post": { "tags": [ "Procurement" ], "summary": "Approve at the caller's level in the routing.", "operationId": "postApiProcurementRequisitionsByIdApprove", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/requisitions/{id}/reject": { "post": { "tags": [ "Procurement" ], "summary": "Reject, with a reason.", "operationId": "postApiProcurementRequisitionsByIdReject", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string" } } }, "example": { "comment": "Stock already on order" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/requisitions/{id}/cancel": { "post": { "tags": [ "Procurement" ], "summary": "Cancel a requisition.", "operationId": "postApiProcurementRequisitionsByIdCancel", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/requisitions/{id}/purchase-orders": { "post": { "tags": [ "Procurement" ], "summary": "Turn an approved requisition into purchase orders, split by vendor.", "operationId": "postApiProcurementRequisitionsByIdPurchaseOrders", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fxRate": { "type": "number" }, "lineIds": { "type": "array", "items": { "type": "string" } }, "supplierByLineId": { "type": "object", "properties": { "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03": { "type": "string" } } }, "singleSupplierId": { "type": "string" }, "expectedDate": { "type": "string", "format": "date" }, "contractId": { "type": "string" }, "notes": { "type": "string" }, "approveImmediately": { "type": "boolean" } } }, "example": { "fxRate": 18.5, "lineIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "supplierByLineId": { "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, "singleSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "expectedDate": "2026-09-01", "contractId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "approveImmediately": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseOrderIds": { "type": "array", "items": { "type": "string" } }, "purchaseOrderNumbers": { "type": "array", "items": { "type": "string" } }, "lineCount": { "type": "integer" }, "totalValue": { "type": "number" }, "skipped": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiMrpConvertResponseSkippedItem" } }, "priceBreakOpportunities": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "description": { "type": "string" }, "supplierName": { "type": "string" }, "orderedQty": { "type": "number" }, "orderedUnitPrice": { "type": "number" }, "orderedTotal": { "type": "number" }, "breakQty": { "type": "number" }, "breakUnitPrice": { "type": "number" }, "breakTotal": { "type": "number" }, "extraUnits": { "type": "number" }, "saving": { "type": "number" } } } } } }, "example": { "purchaseOrderIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "purchaseOrderNumbers": [ "PO-0001" ], "lineCount": 3, "totalValue": 10005.0, "skipped": [ { "plannedOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year." } ], "priceBreakOpportunities": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "supplierName": "Karoo Fresh Holdings Ltd", "orderedQty": 3.0, "orderedUnitPrice": 2900.0, "orderedTotal": 10005.0, "breakQty": 3.0, "breakUnitPrice": 2900.0, "breakTotal": 10005.0, "extraUnits": 1.0, "saving": 1.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/approval-rules": { "get": { "tags": [ "Procurement" ], "summary": "The approval routing — who approves what, at what value.", "operationId": "getApiProcurementApprovalRules", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "stepNo": { "type": "integer" }, "minAmount": { "type": "number" }, "maxAmount": { "type": "number" }, "approverRoleId": { "type": "string" }, "approverRoleName": { "type": "string" }, "approverUserId": { "type": "string" }, "approverUserName": { "type": "string" }, "budgetAccountId": { "type": "string" }, "costCentreId": { "type": "string" }, "isActive": { "type": "boolean" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "stepNo": 1, "minAmount": 10005.0, "maxAmount": 10005.0, "approverRoleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "approverRoleName": "Karoo Fresh Holdings Ltd", "approverUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "approverUserName": "Karoo Fresh Holdings Ltd", "budgetAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Procurement" ], "summary": "Add an approval rule.", "operationId": "postApiProcurementApprovalRules", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productCategory": { "type": "string" }, "supplierId": { "type": "string" }, "clientId": { "type": "string" }, "name": { "type": "string" }, "stepNo": { "type": "integer" }, "minAmount": { "type": "number" }, "maxAmount": { "type": "number" }, "approverRoleId": { "type": "string" }, "approverUserId": { "type": "string" }, "budgetAccountId": { "type": "string" }, "costCentreId": { "type": "string" }, "isActive": { "type": "boolean" } } }, "example": { "productCategory": "hardware", "supplierId": "edaf88e6-33ef-5aaa-8def-1138f7029bda", "clientId": "28431a10-e640-5b59-a80b-412e9ecc424f", "name": "Karoo Fresh Holdings Ltd", "stepNo": 2, "minAmount": 10005.0, "maxAmount": 50000.0, "approverRoleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "approverUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "budgetAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpForecastsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/approval-rules/{id}": { "delete": { "tags": [ "Procurement" ], "summary": "Remove an approval rule.", "operationId": "deleteApiProcurementApprovalRulesById", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/approval-rules/options": { "get": { "tags": [ "Procurement" ], "summary": "Who an approval rule may name (people and roles that can approve purchases), and the cost centres and item categories a rule may be narrowed to.", "operationId": "getApiProcurementApprovalRulesOptions", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "roleName": { "type": "string" } } } }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "costCentres": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } } } }, "example": { "users": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "roleName": "Karoo Fresh Holdings Ltd" } ], "roles": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ], "costCentres": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ], "categories": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/approval-delegations": { "get": { "tags": [ "Procurement" ], "summary": "Cover while an approver is away: who stands in for whom, from when to when.", "operationId": "getApiProcurementApprovalDelegations", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "userName": { "type": "string" }, "delegateUserId": { "type": "string" }, "delegateName": { "type": "string" }, "startsOn": { "type": "string", "format": "date" }, "endsOn": { "type": "string", "format": "date" }, "reason": { "type": "string" }, "activeToday": { "type": "boolean" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userName": "Thandi Mokoena", "delegateUserId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "delegateName": "Karoo Fresh Holdings Ltd", "startsOn": "2026-09-01", "endsOn": "2026-09-01", "reason": "Budget deferred to the next financial year.", "activeToday": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Procurement" ], "summary": "Appoint a stand-in who may decide what waits on an approver for a period. Your own cover needs approval rights; somebody else's needs edit rights.", "operationId": "postApiProcurementApprovalDelegations", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "clientId": { "type": "string" }, "delegateUserId": { "type": "string" }, "startsOn": { "type": "string", "format": "date" }, "endsOn": { "type": "string", "format": "date" }, "reason": { "type": "string" } } }, "example": { "userId": "5f2f93c3-4b3f-50c5-bba9-61121084fc0c", "clientId": "dd58eddb-21ff-5cfe-9b7b-4251193a1cfa", "delegateUserId": "b8fb24bf-f65e-5730-8c45-a314ee0bb216", "startsOn": "2026-10-01", "endsOn": "2026-10-14", "reason": "Annual leave" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpForecastsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/approval-delegations/{id}": { "delete": { "tags": [ "Procurement" ], "summary": "End a stand-in's cover early.", "operationId": "deleteApiProcurementApprovalDelegationsById", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/replenishment": { "get": { "tags": [ "Procurement" ], "summary": "Items at or below their reorder point, with the quantity to order from each approved supplier (reorder quantity or shortfall, rounded up to the supplier's minimum and pack size).", "operationId": "getApiProcurementReplenishment", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "onHand": { "type": "number" }, "reorderPoint": { "type": "number" }, "reorderQty": { "type": "number" }, "wantedQty": { "type": "number" }, "suggestedQty": { "type": "number" }, "minOrderQty": { "type": "number" }, "orderMultiple": { "type": "number" }, "unitPrice": { "type": "number" }, "lineTotal": { "type": "number" } } } }, "estimatedTotal": { "type": "number" } } } }, "skipped": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementReplenishmentResponseSkippedItem" } } } }, "example": { "groups": [ { "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "lines": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "unit": "each", "onHand": 1.0, "reorderPoint": 1.0, "reorderQty": 3.0, "wantedQty": 3.0, "suggestedQty": 3.0, "minOrderQty": 3.0, "orderMultiple": 1.0, "unitPrice": 2900.0, "lineTotal": 8700.0 } ], "estimatedTotal": 10005.0 } ], "skipped": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Procurement" ], "summary": "Raise the chosen low-stock items as purchase requests, one per supplier, optionally sent straight into approval.", "operationId": "postApiProcurementReplenishment", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productIds": { "type": "array", "items": { "type": "string" } }, "submit": { "type": "boolean" } } }, "example": { "productIds": [ "4ea78728-ddfd-5b57-8fd4-e58dca8360d6" ], "submit": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "requisitions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "requisitionNumber": { "type": "string" }, "supplierName": { "type": "string" }, "lineCount": { "type": "integer" }, "estimatedTotal": { "type": "number" }, "status": { "type": "string" } } } }, "skipped": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementReplenishmentResponseSkippedItem" } } } }, "example": { "requisitions": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "requisitionNumber": "INV-0001", "supplierName": "Karoo Fresh Holdings Ltd", "lineCount": 3, "estimatedTotal": 10005.0, "status": "sent" } ], "skipped": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/vendors/suppliers": { "get": { "tags": [ "Procurement" ], "summary": "Supplier contacts an approved-vendor line may name, for the add-a-vendor picker.", "operationId": "getApiProcurementVendorsSuppliers", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/vendors/{id}/status": { "put": { "tags": [ "Procurement" ], "summary": "Block, unblock or mark a vendor row provisional — the status alone; its price, SKU, contract, validity, notes and preferred flag are left as they are.", "operationId": "putApiProcurementVendorsByIdStatus", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "blocked" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "isPreferred": { "type": "boolean" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "blocked", "isPreferred": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/vendors": { "get": { "tags": [ "Procurement" ], "summary": "Approved vendors with their ratings and B-BBEE levels.", "operationId": "getApiProcurementVendors", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiProcurementVendorsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "supplierSku": "LEN-TP-14G4", "status": "sent", "isPreferred": false, "priority": 100, "unitPrice": 2900.0, "currency": "ZAR", "leadTimeDays": 30, "minOrderQty": 3.0, "orderMultiple": 1.0, "contractId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contractNumber": "INV-0001", "validFrom": "2026-09-01", "validTo": "2026-09-30", "onTimeReceipts": 1, "lateReceipts": 1, "onTimePercent": 15.0, "priceBreakCount": 3, "unavailableReason": "Budget deferred to the next financial year.", "notes": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Procurement" ], "summary": "Approve a supplier as a vendor, or change their standing. On an existing vendor, a field left out keeps its stored value.", "operationId": "putApiProcurementVendors", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "supplierId": { "type": "string" }, "supplierSku": { "type": "string" }, "status": { "type": "string" }, "isPreferred": { "type": "boolean" }, "priority": { "type": "integer" }, "unitPrice": { "type": "number" }, "currency": { "type": "string" }, "leadTimeDays": { "type": "integer" }, "minOrderQty": { "type": "number" }, "orderMultiple": { "type": "number" }, "contractId": { "type": "string" }, "validFrom": { "type": "string", "format": "date" }, "validTo": { "type": "string", "format": "date" }, "notes": { "type": "string" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierSku": "LEN-TP-14G4", "status": "approved", "isPreferred": false, "priority": 1, "unitPrice": 2900.0, "currency": "ZAR", "leadTimeDays": 30, "minOrderQty": 3.0, "orderMultiple": 1.0, "contractId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "validFrom": "2026-09-01", "validTo": "2026-09-30", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiProcurementVendorsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "productName": "Karoo Fresh Holdings Ltd", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "supplierSku": "LEN-TP-14G4", "status": "sent", "isPreferred": false, "priority": 100, "unitPrice": 2900.0, "currency": "ZAR", "leadTimeDays": 30, "minOrderQty": 3.0, "orderMultiple": 1.0, "contractId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contractNumber": "INV-0001", "validFrom": "2026-09-01", "validTo": "2026-09-30", "onTimeReceipts": 1, "lateReceipts": 1, "onTimePercent": 15.0, "priceBreakCount": 3, "unavailableReason": "Budget deferred to the next financial year.", "notes": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/vendors/{id}": { "delete": { "tags": [ "Procurement" ], "summary": "Withdraw vendor approval.", "operationId": "deleteApiProcurementVendorsById", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/vendors/unsourced": { "get": { "tags": [ "Procurement" ], "summary": "Parts flagged buy with no approved vendor — the list that stops an MRP run producing a usable answer.", "operationId": "getApiProcurementVendorsUnsourced", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBomOverviewResponseMissingBomsItem" } }, "example": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "qty": 3.0, "sourceType": "invoice", "onHand": 1.0, "shortfall": 1.0, "unitCost": 2900.0, "extendedCost": 10005.0, "leadTimeDays": 30, "supplierName": "Karoo Fresh Holdings Ltd" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/vendors/{id}/price-breaks": { "get": { "tags": [ "Procurement" ], "summary": "A vendor's quantity price breaks.", "operationId": "getApiProcurementVendorsByIdPriceBreaks", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementVendorsByIdPriceBreaksResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "minQty": 3.0, "unitPrice": 2900.0, "note": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Procurement" ], "summary": "Set a vendor's price breaks.", "operationId": "putApiProcurementVendorsByIdPriceBreaks", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "breaks": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementVendorsByIdPriceBreaksResponseItem" } } } }, "example": { "breaks": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "minQty": 3.0, "unitPrice": 79.9, "note": "Budget deferred to the next financial year." } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementVendorsByIdPriceBreaksResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "minQty": 3.0, "unitPrice": 2900.0, "note": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/contracts": { "get": { "tags": [ "Procurement" ], "summary": "Supply contracts and their coverage.", "operationId": "getApiProcurementContracts", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "contractNumber": { "type": "string" }, "title": { "type": "string" }, "contractType": { "type": "string" }, "status": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "committedValue": { "type": "number" }, "consumedValue": { "type": "number" }, "remainingValue": { "type": "number" }, "discountPercent": { "type": "number" }, "paymentTermsDays": { "type": "integer" }, "bbbeeLevel": { "type": "integer" }, "incoterms": { "type": "string" }, "deliveryAddress": { "type": "string" }, "terms": { "type": "string" }, "notes": { "type": "string" }, "renewalNoticeDays": { "type": "integer" }, "daysToExpiry": { "type": "integer" }, "productCount": { "type": "integer" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "contractNumber": "INV-0001", "title": "Karoo Fresh Holdings Ltd", "contractType": "standard", "status": "sent", "startDate": "2026-09-01", "endDate": "2026-09-30", "currency": "ZAR", "committedValue": 10005.0, "consumedValue": 10005.0, "remainingValue": 10005.0, "discountPercent": 0.0, "paymentTermsDays": 30, "bbbeeLevel": 1, "incoterms": "text", "deliveryAddress": "12 Long Street, Cape Town, 8001", "terms": "Goods remain the property of the seller until paid in full.", "notes": "Budget deferred to the next financial year.", "renewalNoticeDays": 30, "daysToExpiry": 30, "productCount": 3 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Procurement" ], "summary": "Record a contract.", "operationId": "postApiProcurementContracts", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "openingConsumedValue": { "type": "number" }, "supplierId": { "type": "string" }, "title": { "type": "string" }, "contractNumber": { "type": "string" }, "contractType": { "type": "string" }, "status": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "committedValue": { "type": "number" }, "discountPercent": { "type": "number" }, "paymentTermsDays": { "type": "integer" }, "bbbeeLevel": { "type": "integer" }, "incoterms": { "type": "string" }, "deliveryAddress": { "type": "string" }, "terms": { "type": "string" }, "notes": { "type": "string" }, "renewalNoticeDays": { "type": "integer" } } }, "example": { "openingConsumedValue": 0.0, "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "title": "Karoo Fresh Holdings Ltd", "contractNumber": "SUP-2026-04", "contractType": "blanket", "status": "draft", "startDate": "2026-09-01", "endDate": "2027-08-31", "currency": "ZAR", "committedValue": 10005.0, "discountPercent": 0.0, "paymentTermsDays": 30, "bbbeeLevel": 1, "incoterms": "FOB", "deliveryAddress": "12 Long Street, Cape Town, 8001", "terms": "Goods remain the property of the seller until paid in full.", "notes": "Budget deferred to the next financial year.", "renewalNoticeDays": 30 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpForecastsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/contracts/{id}/status": { "put": { "tags": [ "Procurement" ], "summary": "Activate, suspend or close a contract.", "operationId": "putApiProcurementContractsByIdStatus", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "active" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/supplier-documents/policy": { "get": { "tags": [ "Procurement" ], "summary": "Per kind of supplier document: whether a new supplier must upload it when they register, and whether a lapsed one only warns or blocks new purchase orders.", "operationId": "getApiProcurementSupplierDocumentsPolicy", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementSupplierDocumentsPolicyResponseItem" } }, "example": [ { "kind": "invoice", "label": "Karoo Fresh Holdings Ltd", "expires": true, "consequence": "text", "required": true, "onExpiry": "2026-09-30" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Procurement" ], "summary": "Set the rule for one or more kinds of supplier document. A kind that never expires cannot be set to block on expiry.", "operationId": "putApiProcurementSupplierDocumentsPolicy", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "required": { "type": "boolean" }, "onExpiry": { "type": "string" } } } } } }, "example": { "rules": [ { "kind": "tax_clearance", "required": true, "onExpiry": "block" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementSupplierDocumentsPolicyResponseItem" } }, "example": [ { "kind": "invoice", "label": "Karoo Fresh Holdings Ltd", "expires": true, "consequence": "text", "required": true, "onExpiry": "2026-09-30" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/supplier-registration/link": { "get": { "tags": [ "Procurement" ], "summary": "The supplier self-registration link to share, whether it is open, and the documents it asks for.", "operationId": "getApiProcurementSupplierRegistrationLink", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiProcurementSupplierRegistrationLinkResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiProcurementSupplierRegistrationLinkResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Procurement" ], "summary": "Open or close the registration link, set the note applicants see, or make a new link. Closing or regenerating retires every copy already shared.", "operationId": "putApiProcurementSupplierRegistrationLink", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "intro": { "type": "string" }, "regenerate": { "type": "boolean" } } }, "example": { "enabled": true, "intro": "We buy steel plate and sections for fabrication in Gauteng.", "regenerate": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiProcurementSupplierRegistrationLinkResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiProcurementSupplierRegistrationLinkResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/supplier-registrations": { "get": { "tags": [ "Procurement" ], "summary": "Applications from businesses that registered through the link, newest first. ?status=submitted (the default), accepted, declined or all.", "operationId": "getApiProcurementSupplierRegistrations", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "pending" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string" }, "companyName": { "type": "string" }, "tradingName": { "type": "string" }, "registrationNumber": { "type": "string" }, "vatNumber": { "type": "string" }, "contactName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "supplies": { "type": "string" }, "status": { "type": "string" }, "declineReason": { "type": "string" }, "contactId": { "type": "string" }, "submittedAt": { "type": "string" }, "reviewedAt": { "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "reference": { "type": "string" }, "issuedOn": { "type": "string", "format": "date" }, "expiresOn": { "type": "string", "format": "date" }, "fileUrl": { "type": "string" } } } }, "missingRequired": { "type": "array", "items": { "type": "string" } }, "possibleMatch": { "type": "object", "properties": { "contactId": { "type": "string" }, "name": { "type": "string" }, "matchedOn": { "type": "string", "format": "date" } } } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "companyName": "Karoo Fresh Holdings Ltd", "tradingName": "Karoo Fresh Holdings Ltd", "registrationNumber": "2021/123456/07", "vatNumber": "4123456789", "contactName": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "address": "12 Long Street, Cape Town, 8001", "supplies": "text", "status": "sent", "declineReason": "Budget deferred to the next financial year.", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "submittedAt": "2026-09-01T09:15:00Z", "reviewedAt": "2026-09-01T09:15:00Z", "documents": [ { "kind": "invoice", "label": "Karoo Fresh Holdings Ltd", "reference": "INV-0001", "issuedOn": "2026-09-01", "expiresOn": "2026-09-01", "fileUrl": "https://app.ledgrsa.com/pay/3f1a7c92" } ], "missingRequired": [ "text" ], "possibleMatch": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "matchedOn": "2026-09-01" } } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/supplier-registrations/{id}/accept": { "post": { "tags": [ "Procurement" ], "summary": "Accept an application: it becomes a supplier contact (or joins an existing one), provisionally approved for the items named, with its documents waiting for review. Requires procurement:approve.", "operationId": "postApiProcurementSupplierRegistrationsByIdAccept", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productIds": { "type": "array", "items": { "type": "string" } }, "existingContactId": { "type": "null" } } }, "example": { "productIds": [ "bb866a9b-544a-5857-b5ef-3dc5e39b4fc7" ], "existingContactId": null } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiProcurementSupplierRegistrationsByIdAcceptResponse" }, "example": { "ok": true, "message": "Saved.", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendorRowCount": 3, "applicantEmailed": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/supplier-registrations/{id}/decline": { "post": { "tags": [ "Procurement" ], "summary": "Decline an application. The reason is required and is emailed to the applicant. Requires procurement:approve.", "operationId": "postApiProcurementSupplierRegistrationsByIdDecline", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillsByIdRejectRequest" }, "example": { "reason": "We already have two approved steel suppliers in Gauteng." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiProcurementSupplierRegistrationsByIdAcceptResponse" }, "example": { "ok": true, "message": "Saved.", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vendorRowCount": 3, "applicantEmailed": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/rfqs": { "get": { "tags": [ "Procurement" ], "summary": "Requests for quotation.", "operationId": "getApiProcurementRfqs", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementRfqsByIdResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rfqNumber": "INV-0001", "title": "Karoo Fresh Holdings Ltd", "requisitionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "requisitionNumber": "INV-0001", "status": "sent", "issueDate": "2026-09-01", "responseDueDate": "2026-09-01", "currency": "ZAR", "deliveryAddress": "12 Long Street, Cape Town, 8001", "terms": "Goods remain the property of the seller until paid in full.", "notes": "Budget deferred to the next financial year.", "awardedSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "awardedSupplierName": "Karoo Fresh Holdings Ltd", "awardedQuoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "awardReason": "Budget deferred to the next financial year.", "awardedAt": "2026-09-01T09:15:00Z", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "description": "Consulting services — August 2026", "qty": 3.0, "unit": "each", "requiredDate": "2026-09-01", "requisitionLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quotedPrices": [ { "quoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "unitPrice": 2900.0, "lineTotal": 8700.0, "leadTimeDays": 30, "isLowest": false } ] } ], "suppliers": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "status": "sent", "contactEmail": "accounts@karoofresh.example", "sentAt": "2026-09-01T09:15:00Z", "respondedAt": "2026-09-01T09:15:00Z", "quoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quoteTotal": 10005.0 } ], "quotes": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rfqId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "quoteNumber": "INV-0001", "quoteDate": "2026-09-01", "validUntil": "2026-09-30", "currency": "ZAR", "subtotal": 8700.0, "vatAmount": 1305.0, "total": 10005.0, "leadTimeDays": 30, "paymentTermsDays": 30, "status": "sent", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rfqLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0, "unitPrice": 2900.0, "lineTotal": 8700.0, "leadTimeDays": 30, "notes": "Budget deferred to the next financial year." } ], "isLowest": false } ], "invitedCount": 3, "respondedCount": 3, "lowestQuoteTotal": 10005.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Procurement" ], "summary": "Raise an RFQ.", "operationId": "postApiProcurementRfqs", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "title": { "type": "string" }, "requisitionId": { "type": "string" }, "responseDueDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "deliveryAddress": { "type": "string" }, "terms": { "type": "string" }, "notes": { "type": "string" }, "supplierIds": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "description": { "type": "string" }, "qty": { "type": "number" }, "unit": { "type": "string" }, "requiredDate": { "type": "string", "format": "date" }, "requisitionLineId": { "type": "string" } } } }, "fromRequisitionLines": { "type": "boolean" } } }, "example": { "clientId": "53d05c7b-38e4-5bf4-b9fe-a6e397a60282", "title": "Karoo Fresh Holdings Ltd", "requisitionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "responseDueDate": "2026-09-05", "currency": "ZAR", "deliveryAddress": "12 Long Street, Cape Town, 8001", "terms": "Goods remain the property of the seller until paid in full.", "notes": "Budget deferred to the next financial year.", "supplierIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "lines": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0, "unit": "each", "requiredDate": "2026-09-01", "requisitionLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "fromRequisitionLines": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpForecastsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/rfqs/{id}": { "get": { "tags": [ "Procurement" ], "summary": "One RFQ and the quotes received.", "operationId": "getApiProcurementRfqsById", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiProcurementRfqsByIdResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rfqNumber": "INV-0001", "title": "Karoo Fresh Holdings Ltd", "requisitionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "requisitionNumber": "INV-0001", "status": "sent", "issueDate": "2026-09-01", "responseDueDate": "2026-09-01", "currency": "ZAR", "deliveryAddress": "12 Long Street, Cape Town, 8001", "terms": "Goods remain the property of the seller until paid in full.", "notes": "Budget deferred to the next financial year.", "awardedSupplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "awardedSupplierName": "Karoo Fresh Holdings Ltd", "awardedQuoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "awardReason": "Budget deferred to the next financial year.", "awardedAt": "2026-09-01T09:15:00Z", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "description": "Consulting services — August 2026", "qty": 3.0, "unit": "each", "requiredDate": "2026-09-01", "requisitionLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quotedPrices": [ { "quoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "unitPrice": 2900.0, "lineTotal": 8700.0, "leadTimeDays": 30, "isLowest": false } ] } ], "suppliers": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "status": "sent", "contactEmail": "accounts@karoofresh.example", "sentAt": "2026-09-01T09:15:00Z", "respondedAt": "2026-09-01T09:15:00Z", "quoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quoteTotal": 10005.0 } ], "quotes": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rfqId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "quoteNumber": "INV-0001", "quoteDate": "2026-09-01", "validUntil": "2026-09-30", "currency": "ZAR", "subtotal": 8700.0, "vatAmount": 1305.0, "total": 10005.0, "leadTimeDays": 30, "paymentTermsDays": 30, "status": "sent", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rfqLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0, "unitPrice": 2900.0, "lineTotal": 8700.0, "leadTimeDays": 30, "notes": "Budget deferred to the next financial year." } ], "isLowest": false } ], "invitedCount": 3, "respondedCount": 3, "lowestQuoteTotal": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/rfqs/{id}/send": { "post": { "tags": [ "Procurement" ], "summary": "Send the RFQ to its vendors.", "operationId": "postApiProcurementRfqsByIdSend", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/rfqs/{id}/quotes": { "post": { "tags": [ "Procurement" ], "summary": "Capture a quote received off-platform.", "operationId": "postApiProcurementRfqsByIdQuotes", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "supplierId": { "type": "string" }, "quoteNumber": { "type": "string" }, "quoteDate": { "type": "string", "format": "date" }, "validUntil": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "leadTimeDays": { "type": "integer" }, "paymentTermsDays": { "type": "integer" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "rfqLineId": { "type": "string" }, "description": { "type": "string" }, "qty": { "type": "number" }, "unitPrice": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "notes": { "type": "string" } } } } } }, "example": { "clientId": "e271206c-5641-552c-b44d-77d35f1156d4", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quoteNumber": "INV-0001", "quoteDate": "2026-09-01", "validUntil": "2026-09-30", "currency": "ZAR", "leadTimeDays": 30, "paymentTermsDays": 30, "notes": "Budget deferred to the next financial year.", "lines": [ { "rfqLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0, "unitPrice": 81.0, "leadTimeDays": 7, "notes": "Budget deferred to the next financial year." } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpForecastsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/rfqs/{id}/award": { "post": { "tags": [ "Procurement" ], "summary": "Award the RFQ and raise the order.", "operationId": "postApiProcurementRfqsByIdAward", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lineAwards": { "type": "array", "items": { "type": "object" } }, "quoteId": { "type": "string" }, "reason": { "type": "string" }, "addToApprovedVendors": { "type": "boolean" }, "createPurchaseOrder": { "type": "boolean" } } }, "example": { "lineAwards": [], "quoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reason": "Budget deferred to the next financial year.", "addToApprovedVendors": true, "createPurchaseOrder": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "purchaseOrderIds": { "type": "string" } } }, "example": { "status": "awarded", "purchaseOrderIds": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/purchase-orders": { "get": { "tags": [ "Procurement" ], "summary": "Purchase orders from the buyer's side, with their transmission state.", "operationId": "getApiProcurementPurchaseOrders", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "includeClosed", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" }, { "name": "overdueOnly", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPurchaseOrdersResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPurchaseOrdersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/purchase-orders/{id}/transmit": { "post": { "tags": [ "Procurement" ], "summary": "Send the order to the vendor.", "operationId": "postApiProcurementPurchaseOrdersByIdTransmit", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string" }, "to": { "type": "string", "format": "date" }, "message": { "type": "string" } } }, "example": { "channel": "email", "to": "2026-09-30", "message": "Saved." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "channel": { "type": "string" }, "to": { "type": "string", "format": "date" }, "number": { "type": "string" }, "delivered": { "type": "integer" }, "error": { "type": "string" } } }, "example": { "status": "sent", "channel": "email", "to": "2026-09-30", "number": "INV-0001", "delivered": 1, "error": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/matches": { "get": { "tags": [ "Procurement" ], "summary": "The three-way match — order against receipt against bill — and what does not agree.", "operationId": "getApiProcurementMatches", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "exceptionsOnly", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementMatchesResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billNumber": "INV-0001", "vendorName": "Karoo Fresh Holdings Ltd", "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001", "goodsReceiptId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "goodsReceiptNumber": "INV-0001", "status": "sent", "poTotal": 10005.0, "receiptTotal": 10005.0, "invoiceTotal": 10005.0, "priceVariance": 10005.0, "priceVariancePercent": 15.0, "qtyVariance": 1.0, "toleranceAmount": 10005.0, "tolerancePercent": 15.0, "lines": [ { "description": "Consulting services — August 2026", "qtyOrdered": 1.0, "qtyReceived": 1.0, "qtyBilled": 1.0, "lineMatched": false, "priceOrdered": 10005.0, "priceReceived": 10005.0, "priceVariance": 10005.0, "qtyVariance": 1.0, "withinTolerance": true, "note": "Budget deferred to the next financial year." } ], "matchedAt": "2026-09-01T09:15:00Z", "resolvedAt": "2026-09-01T09:15:00Z", "resolvedByName": "Karoo Fresh Holdings Ltd", "resolutionNote": "Budget deferred to the next financial year.", "blocksPayment": false, "matchBasis": "invoice", "overBilledQty": 3.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/matches/{billId}": { "post": { "tags": [ "Procurement" ], "summary": "Run the match for one bill.", "operationId": "postApiProcurementMatchesByBillId", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "billId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiProcurementMatchesResponseItem" }, "examples": { "default": { "$ref": "#/components/examples/PostApiProcurementMatchesByBillIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/matches/{billId}/resolve": { "post": { "tags": [ "Procurement" ], "summary": "Accept or write off a matching difference.", "operationId": "postApiProcurementMatchesByBillIdResolve", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "billId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accept": { "type": "boolean" }, "note": { "type": "string" } } }, "example": { "accept": true, "note": "Freight not on the order" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiProcurementMatchesResponseItem" }, "examples": { "default": { "$ref": "#/components/examples/PostApiProcurementMatchesByBillIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/settings": { "get": { "tags": [ "Procurement" ], "summary": "Procurement settings — tolerances, required approvals, whether a receipt is mandatory before a bill.", "operationId": "getApiProcurementSettings", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "overReceiptTolerancePercent": { "type": "number" }, "priceTolerancePercent": { "type": "number" }, "priceToleranceAmount": { "type": "number" }, "requireRequisitionForPo": { "type": "boolean" }, "autoApproveBelow": { "type": "number" }, "minQuotesForAward": { "type": "integer" }, "defaultPaymentTermsDays": { "type": "integer" }, "defaultCurrency": { "type": "string" }, "requisitionPrefix": { "type": "string" }, "rfqPrefix": { "type": "string" }, "workOrderPrefix": { "type": "string" }, "mrpRunPrefix": { "type": "string" } } }, "example": { "overReceiptTolerancePercent": 15.0, "priceTolerancePercent": 15.0, "priceToleranceAmount": 10005.0, "requireRequisitionForPo": false, "autoApproveBelow": 1.0, "minQuotesForAward": 1, "defaultPaymentTermsDays": 30, "defaultCurrency": "ZAR", "requisitionPrefix": "INV-", "rfqPrefix": "INV-", "workOrderPrefix": "INV-", "mrpRunPrefix": "INV-" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Procurement" ], "summary": "Change the procurement settings.", "operationId": "putApiProcurementSettings", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "overReceiptTolerancePercent": { "type": "number" }, "priceTolerancePercent": { "type": "number" }, "priceToleranceAmount": { "type": "number" }, "requireRequisitionForPo": { "type": "boolean" }, "autoApproveBelow": { "type": "number" }, "minQuotesForAward": { "type": "integer" }, "defaultPaymentTermsDays": { "type": "integer" }, "defaultCurrency": { "type": "string" }, "requisitionPrefix": { "type": "string" }, "rfqPrefix": { "type": "string" }, "workOrderPrefix": { "type": "string" }, "mrpRunPrefix": { "type": "string" }, "matchPaymentHold": { "type": "string" } } }, "example": { "overReceiptTolerancePercent": 15.0, "priceTolerancePercent": 2.0, "priceToleranceAmount": 10005.0, "requireRequisitionForPo": true, "autoApproveBelow": 1.0, "minQuotesForAward": 1, "defaultPaymentTermsDays": 30, "defaultCurrency": "ZAR", "requisitionPrefix": "PR-", "rfqPrefix": "RFQ-", "workOrderPrefix": "WO-", "mrpRunPrefix": "MRP-", "matchPaymentHold": "hold" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "updated" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/bbbee-spend": { "get": { "tags": [ "Procurement" ], "summary": "Preferential procurement spend by supplier B-BBEE level, which feeds the scorecard element.", "operationId": "getApiProcurementBbbeeSpend", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "asOf": { "type": "string" }, "totalMeasuredSpend": { "type": "number" }, "recognisedSpend": { "type": "number" }, "recognisedPercent": { "type": "number" }, "emeSpend": { "type": "number" }, "qseSpend": { "type": "number" }, "blackOwnedSpend": { "type": "number" }, "blackWomanOwnedSpend": { "type": "number" }, "unratedSpend": { "type": "number" }, "expiredSpend": { "type": "number" }, "recoverableByRenewal": { "type": "number" }, "supplierCount": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "spend": { "type": "number" }, "statedLevel": { "type": "integer" }, "levelWasDeemed": { "type": "boolean" }, "effectiveLevel": { "type": "integer" }, "levelLabel": { "type": "string" }, "certificateExpiry": { "type": "string", "format": "date" }, "certificateExpired": { "type": "boolean" }, "recognitionPercent": { "type": "number" }, "recognisedSpend": { "type": "number" }, "recoverableByRenewal": { "type": "number" }, "isEme": { "type": "boolean" }, "isQse": { "type": "boolean" }, "blackOwnedPercent": { "type": "number" }, "blackWomanOwnedPercent": { "type": "number" }, "invoiceCount": { "type": "integer" } } } } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "asOf": "text", "totalMeasuredSpend": 10005.0, "recognisedSpend": 1.0, "recognisedPercent": 15.0, "emeSpend": 1.0, "qseSpend": 1.0, "blackOwnedSpend": 1.0, "blackWomanOwnedSpend": 1.0, "unratedSpend": 1.0, "expiredSpend": 1.0, "recoverableByRenewal": 1.0, "supplierCount": 3, "lines": [ { "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "spend": 1.0, "statedLevel": 1, "levelWasDeemed": false, "effectiveLevel": 1, "levelLabel": "Karoo Fresh Holdings Ltd", "certificateExpiry": "2026-09-30", "certificateExpired": false, "recognitionPercent": 15.0, "recognisedSpend": 1.0, "recoverableByRenewal": 1.0, "isEme": false, "isQse": false, "blackOwnedPercent": 15.0, "blackWomanOwnedPercent": 15.0, "invoiceCount": 3 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/suppliers/{id}/bbbee": { "put": { "tags": [ "Procurement" ], "summary": "Record a supplier's B-BBEE level and certificate expiry.", "operationId": "putApiProcurementSuppliersByIdBbbee", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "level": { "type": "integer" }, "certificateExpiry": { "type": "string", "format": "date" }, "isEme": { "type": "boolean" }, "isQse": { "type": "boolean" }, "blackOwnedPercent": { "type": "number" }, "blackWomanOwnedPercent": { "type": "number" }, "certificateRef": { "type": "string" } } }, "example": { "level": 2, "certificateExpiry": "2027-03-31", "isEme": true, "isQse": true, "blackOwnedPercent": 15.0, "blackWomanOwnedPercent": 15.0, "certificateRef": "INV-0001" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "saved" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/products": { "get": { "tags": [ "Procurement" ], "summary": "The products a purchase request line, an approved vendor or a supplier's catalogue item may name — id, SKU, name, whether stock is tracked and the product's units. The same list as /api/bom/products, read under procurement:view, because a tenant on Business with the Procurement add-on does not license BOM.", "operationId": "getApiProcurementProducts", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cup" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiBomProductsResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "CUP-250", "name": "Paper cup 250ml (sleeve of 50)", "isTracked": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/coding-options": { "get": { "tags": [ "Procurement" ], "summary": "The cost centres and GL accounts a purchase may be coded to, for the active company.", "operationId": "getApiProcurementCodingOptions", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "costCentres": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementCodingOptionsResponseAccountsItem" } }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementCodingOptionsResponseAccountsItem" } } } }, "example": { "costCentres": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "kind": "standard" } ], "accounts": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "kind": "standard" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/purchase-orders/{id}/coding": { "put": { "tags": [ "Procurement" ], "summary": "Re-code a draft purchase order: its cost centre and each line's own cost centre and account.", "operationId": "putApiProcurementPurchaseOrdersByIdCoding", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "costCentreId": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string" }, "costCentreId": { "type": "string" }, "accountId": { "type": "string" } } } } } }, "example": { "accountId": "4a1215ab-22f9-50b3-b002-723ec48c343a", "costCentreId": "0a4f4aa1-b7dc-59cc-9cd4-fd01927b8fb9", "lines": [ { "lineId": "d71b9f56-9052-56b1-9fef-274c088c6a22", "costCentreId": "46533f02-0b9e-5375-9cba-aad23feb4122", "accountId": "e65cd49a-04f4-5eff-8eb5-7743db4252f2" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "coded" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/budgets": { "get": { "tags": [ "Procurement" ], "summary": "Every procurement budget and where it stands: actual, committed and what is left.", "operationId": "getApiProcurementBudgets", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "accountId": { "type": "string" }, "accountName": { "type": "string" }, "costCentreId": { "type": "string" }, "costCentreName": { "type": "string" }, "amount": { "type": "number" }, "policy": { "type": "string" }, "actual": { "type": "number" }, "committed": { "type": "number" }, "available": { "type": "number" }, "usedPercent": { "type": "number" }, "summary": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountName": "Karoo Fresh Holdings Ltd", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreName": "Karoo Fresh Holdings Ltd", "amount": 10005.0, "policy": "fifo", "actual": 1.0, "committed": 1.0, "available": 1.0, "usedPercent": 15.0, "summary": "Consulting services — August 2026" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Procurement" ], "summary": "Add a procurement budget for an account, a cost centre or both, with what happens when a purchase would go over.", "operationId": "postApiProcurementBudgets", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "clientId": { "type": "string" }, "name": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "costCentreId": { "type": "string" }, "amount": { "type": "number" }, "policy": { "type": "string" } } }, "example": { "accountId": "2985214f-008c-50a0-b2a3-4850d0b8bb4f", "clientId": "6ee6a6e0-afda-5f5c-aedd-4fe2f848a739", "name": "Workshop, September", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "costCentreId": "cdb8606e-8257-5a0c-a39d-633747284541", "amount": 25000.0, "policy": "require_approval" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpForecastsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/budgets/{id}": { "put": { "tags": [ "Procurement" ], "summary": "Change a procurement budget.", "operationId": "putApiProcurementBudgetsById", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "costCentreId": { "type": "string" }, "clientId": { "type": "string" }, "name": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "accountId": { "type": "string" }, "amount": { "type": "number" }, "policy": { "type": "string" } } }, "example": { "costCentreId": "eaf3783a-41a3-5564-a39e-3c489f6f649f", "clientId": "3252abdc-b93e-50af-9881-91bd27e15407", "name": "Workshop, September", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "accountId": "269c4a12-cd72-586e-93c2-fdcd713cdb6e", "amount": 30000.0, "policy": "warn" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "saved" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Procurement" ], "summary": "Remove a procurement budget.", "operationId": "deleteApiProcurementBudgetsById", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/requisitions/{id}/budget-impact": { "get": { "tags": [ "Procurement" ], "summary": "What a purchase request does to each budget it touches.", "operationId": "getApiProcurementRequisitionsByIdBudgetImpact", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementRequisitionsByIdBudgetImpactResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiProcurementRequisitionsByIdBudgetImpactResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/punchout-suppliers": { "get": { "tags": [ "Procurement" ], "summary": "The suppliers whose own web shop a requisition can open — each one with punch-out set up and switched on.", "operationId": "getApiProcurementPunchoutSuppliers", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "contactId": { "type": "string" }, "name": { "type": "string" }, "protocol": { "type": "string" } } } }, "example": [ { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "protocol": "text" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/suppliers/{contactId}/punchout": { "get": { "tags": [ "Procurement" ], "summary": "A supplier's punch-out set-up: cXML or OCI, the shop's set-up address and the identities it expects. The shared secret is never returned; hasSecret says whether one is held.", "operationId": "getApiProcurementSuppliersByContactIdPunchout", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiProcurementSuppliersByContactIdPunchoutResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiProcurementSuppliersByContactIdPunchoutResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Procurement" ], "summary": "Set up punch-out to a supplier's shop. The set-up address must be https. A blank sharedSecret keeps the one held; the secret is stored encrypted.", "operationId": "putApiProcurementSuppliersByContactIdPunchout", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiProcurementSuppliersByContactIdPunchoutResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiProcurementSuppliersByContactIdPunchoutResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/requisitions/{id}/punchout": { "post": { "tags": [ "Procurement" ], "summary": "Open the supplier's shop from a draft requisition. Answers the address to open; the cart the shop sends back becomes lines on this requisition at the cart's prices, and the requisition stays a draft for its approval rules. The return address is good once, for an hour.", "operationId": "postApiProcurementRequisitionsByIdPunchout", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "startUrl": { "type": "string" }, "expiresInMinutes": { "type": "integer" } } }, "example": { "startUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "expiresInMinutes": 60 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/purchase-orders/{id}/budget-impact": { "get": { "tags": [ "Procurement" ], "summary": "What a purchase order does to each budget it touches, and whether an overspend is waiting on a decision.", "operationId": "getApiProcurementPurchaseOrdersByIdBudgetImpact", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiProcurementRequisitionsByIdBudgetImpactResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiProcurementRequisitionsByIdBudgetImpactResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/purchase-orders/{id}/budget-approval/{budgetId}": { "post": { "tags": [ "Procurement" ], "summary": "Agree to, or decline, a purchase order's overspend on one budget. Declining needs a reason.", "operationId": "postApiProcurementPurchaseOrdersByIdBudgetApprovalByBudgetId", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "budgetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approve": { "type": "boolean" }, "comment": { "type": "string" } } }, "example": { "approve": false, "comment": "Hold this until the March budget opens" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/spend": { "get": { "tags": [ "Procurement" ], "summary": "Posted supplier spend and open order value grouped by supplier, category, cost centre or month, against the period before.", "operationId": "getApiProcurementSpend", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "groupBy", "in": "query", "required": false, "schema": { "type": "string" }, "example": "supplier" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "25" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "previousFrom": { "type": "string", "format": "date" }, "previousTo": { "type": "string", "format": "date" }, "groupBy": { "type": "string" }, "totalPosted": { "type": "number" }, "totalPreviousPosted": { "type": "number" }, "totalCommitted": { "type": "number" }, "changePercent": { "type": "number" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "posted": { "type": "number" }, "previousPosted": { "type": "number" }, "committed": { "type": "number" }, "changePercent": { "type": "number" }, "sharePercent": { "type": "number" } } } }, "groupCount": { "type": "integer" }, "otherPosted": { "type": "number" }, "otherCommitted": { "type": "number" } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "previousFrom": "2026-09-01", "previousTo": "2026-09-30", "groupBy": "text", "totalPosted": 10005.0, "totalPreviousPosted": 10005.0, "totalCommitted": 10005.0, "changePercent": 15.0, "rows": [ { "key": "text", "label": "Karoo Fresh Holdings Ltd", "posted": 1.0, "previousPosted": 1.0, "committed": 1.0, "changePercent": 15.0, "sharePercent": 15.0 } ], "groupCount": 3, "otherPosted": 1.0, "otherCommitted": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/spend/price-trend": { "get": { "tags": [ "Procurement" ], "summary": "The price paid per product over time, from goods receipts.", "operationId": "getApiProcurementSpendPriceTrend", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "af7cd2b6-edec-51be-a94d-f4afee91aba0" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Clamped rather than refused: a value of 0 or below is treated as the default, and one above the maximum is treated as the maximum.", "schema": { "type": "integer" }, "example": "10" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "receiptCount": { "type": "integer" }, "quantity": { "type": "number" }, "spend": { "type": "number" }, "firstUnitCost": { "type": "number" }, "lastUnitCost": { "type": "number" }, "minUnitCost": { "type": "number" }, "maxUnitCost": { "type": "number" }, "averageUnitCost": { "type": "number" }, "changePercent": { "type": "number" }, "points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "unitCost": { "type": "number" }, "qty": { "type": "number" }, "supplierName": { "type": "string" } } } } } } }, "productCount": { "type": "integer" } } }, "example": { "from": "2026-09-01", "to": "2026-09-30", "products": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sku": "LEN-TP-14G4", "name": "Karoo Fresh Holdings Ltd", "receiptCount": 3, "quantity": 3.0, "spend": 1.0, "firstUnitCost": 2900.0, "lastUnitCost": 2900.0, "minUnitCost": 2900.0, "maxUnitCost": 2900.0, "averageUnitCost": 2900.0, "changePercent": 15.0, "points": [ { "date": "2026-09-01", "unitCost": 2900.0, "qty": 3.0, "supplierName": "Karoo Fresh Holdings Ltd" } ] } ], "productCount": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/session": { "get": { "tags": [ "Supplier portal API" ], "summary": "Who the token belongs to, which buyer they are dealing with, and what they may see.", "operationId": "getSupplierApiV1Session", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "supplierName": { "type": "string" }, "buyerName": { "type": "string" }, "buyerCompanyName": { "type": "string" }, "currency": { "type": "string" }, "ordersAwaitingAcknowledgement": { "type": "integer" }, "openOrders": { "type": "integer" }, "openRfqs": { "type": "integer" }, "invoicesAwaitingAcceptance": { "type": "integer" }, "accessExpiresAt": { "type": "string" }, "complianceNeedingAttention": { "type": "integer" }, "liveOffers": { "type": "integer" }, "adoptedCatalogueItems": { "type": "integer" }, "overdueInvoices": { "type": "integer" }, "overdueAmount": { "type": "number" } } }, "example": { "supplierName": "Karoo Fresh Holdings Ltd", "buyerName": "Karoo Fresh Holdings Ltd", "buyerCompanyName": "Karoo Fresh Holdings Ltd", "currency": "ZAR", "ordersAwaitingAcknowledgement": 1, "openOrders": 1, "openRfqs": 1, "invoicesAwaitingAcceptance": 1, "accessExpiresAt": "2026-09-01T09:15:00Z", "complianceNeedingAttention": 1, "liveOffers": 1, "adoptedCatalogueItems": 1, "overdueInvoices": 1, "overdueAmount": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/orders": { "get": { "tags": [ "Supplier portal API" ], "summary": "Purchase orders addressed to this supplier.", "operationId": "getSupplierApiV1Orders", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1OrdersByIdResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "orderNumber": "PO-0001", "issueDate": "2026-09-01", "expectedDate": "2026-09-01", "status": "sent", "currency": "ZAR", "subtotal": 8700.0, "vatTotal": 1305.0, "total": 10005.0, "deliveryAddress": "12 Long Street, Cape Town, 8001", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "productCode": "CT-001", "quantity": 3.0, "qtyReceived": 1.0, "unitPrice": 2900.0, "vatRate": 15.0, "lineTotal": 10005.0 } ], "acknowledgedAt": "2026-09-01T09:15:00Z", "acknowledgedBy": "text", "ackStatus": "sent", "promisedDate": "2026-09-01", "ackNote": "Budget deferred to the next financial year.", "canAcknowledge": false, "canInvoice": false, "submittedInvoices": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "net": 8700.0, "vat": 1305.0, "gross": 1.0, "currency": "ZAR", "status": "sent", "submittedAt": "2026-09-01T09:15:00Z", "orderNumber": "PO-0001", "lines": [ { "description": "Consulting services — August 2026", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "lineTotal": 10005.0, "vatAmount": 1305.0 } ], "canWithdraw": false, "matchStatus": "sent", "matchNote": "Budget deferred to the next financial year." } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/orders/{id}": { "get": { "tags": [ "Supplier portal API" ], "summary": "One order with its lines and delivery requirements.", "operationId": "getSupplierApiV1OrdersById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSupplierApiV1OrdersByIdResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "orderNumber": "PO-0001", "issueDate": "2026-09-01", "expectedDate": "2026-09-01", "status": "sent", "currency": "ZAR", "subtotal": 8700.0, "vatTotal": 1305.0, "total": 10005.0, "deliveryAddress": "12 Long Street, Cape Town, 8001", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "productCode": "CT-001", "quantity": 3.0, "qtyReceived": 1.0, "unitPrice": 2900.0, "vatRate": 15.0, "lineTotal": 10005.0 } ], "acknowledgedAt": "2026-09-01T09:15:00Z", "acknowledgedBy": "text", "ackStatus": "sent", "promisedDate": "2026-09-01", "ackNote": "Budget deferred to the next financial year.", "canAcknowledge": false, "canInvoice": false, "submittedInvoices": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "net": 8700.0, "vat": 1305.0, "gross": 1.0, "currency": "ZAR", "status": "sent", "submittedAt": "2026-09-01T09:15:00Z", "orderNumber": "PO-0001", "lines": [ { "description": "Consulting services — August 2026", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "lineTotal": 10005.0, "vatAmount": 1305.0 } ], "canWithdraw": false, "matchStatus": "sent", "matchNote": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/orders/{id}/acknowledge": { "post": { "tags": [ "Supplier portal API" ], "summary": "Acknowledge an order, with a promised date.", "operationId": "postSupplierApiV1OrdersByIdAcknowledge", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string" }, "signedBy": { "type": "string" }, "promisedDate": { "type": "string", "format": "date" }, "note": { "type": "string" } } }, "example": { "decision": "accepted", "signedBy": "Thandi Mokoena", "promisedDate": "2026-09-08", "note": "Full quantity available" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierApiV1OffersResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostSupplierApiV1OffersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/rfqs": { "get": { "tags": [ "Supplier portal API" ], "summary": "RFQs this supplier has been invited to.", "operationId": "getSupplierApiV1Rfqs", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1RfqsByIdResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rfqNumber": "INV-0001", "title": "Karoo Fresh Holdings Ltd", "issueDate": "2026-09-01", "responseDueDate": "2026-09-01", "currency": "ZAR", "deliveryAddress": "12 Long Street, Cape Town, 8001", "terms": "Goods remain the property of the seller until paid in full.", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "quantity": 3.0, "unit": "each", "requiredDate": "2026-09-01" } ], "invitationStatus": "sent", "canQuote": false, "submittedQuote": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quoteNumber": "INV-0001", "quoteDate": "2026-09-01", "validUntil": "2026-09-30", "currency": "ZAR", "subtotal": 8700.0, "vatAmount": 1305.0, "total": 10005.0, "leadTimeDays": 30, "paymentTermsDays": 30, "status": "sent", "notes": "Budget deferred to the next financial year.", "lines": [ { "rfqLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "leadTimeDays": 30, "notes": "Budget deferred to the next financial year.", "lineTotal": 10005.0 } ] } } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/rfqs/{id}": { "get": { "tags": [ "Supplier portal API" ], "summary": "One RFQ and its lines.", "operationId": "getSupplierApiV1RfqsById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSupplierApiV1RfqsByIdResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rfqNumber": "INV-0001", "title": "Karoo Fresh Holdings Ltd", "issueDate": "2026-09-01", "responseDueDate": "2026-09-01", "currency": "ZAR", "deliveryAddress": "12 Long Street, Cape Town, 8001", "terms": "Goods remain the property of the seller until paid in full.", "notes": "Budget deferred to the next financial year.", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "lineNumber": 1, "description": "Consulting services — August 2026", "quantity": 3.0, "unit": "each", "requiredDate": "2026-09-01" } ], "invitationStatus": "sent", "canQuote": false, "submittedQuote": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quoteNumber": "INV-0001", "quoteDate": "2026-09-01", "validUntil": "2026-09-30", "currency": "ZAR", "subtotal": 8700.0, "vatAmount": 1305.0, "total": 10005.0, "leadTimeDays": 30, "paymentTermsDays": 30, "status": "sent", "notes": "Budget deferred to the next financial year.", "lines": [ { "rfqLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "leadTimeDays": 30, "notes": "Budget deferred to the next financial year.", "lineTotal": 10005.0 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/rfqs/{id}/quote": { "post": { "tags": [ "Supplier portal API" ], "summary": "Submit a quote against an RFQ.", "operationId": "postSupplierApiV1RfqsByIdQuote", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteNumber": { "type": "string" }, "validUntil": { "type": "string", "format": "date" }, "leadTimeDays": { "type": "integer" }, "paymentTermsDays": { "type": "integer" }, "notes": { "type": "string" }, "clientReference": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1OffersResponseItemLinesItem" } } } }, "example": { "quoteNumber": "INV-0001", "validUntil": "2027-03-31", "leadTimeDays": 30, "paymentTermsDays": 30, "notes": "Budget deferred to the next financial year.", "clientReference": "rfq-quote-0001", "lines": [ { "rfqLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 81.0, "leadTimeDays": 7, "notes": "Budget deferred to the next financial year.", "lineTotal": 10005.0 } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierApiV1OffersResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostSupplierApiV1OffersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/invoices": { "get": { "tags": [ "Supplier portal API" ], "summary": "Invoices this supplier has submitted, and their state.", "operationId": "getSupplierApiV1Invoices", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1InvoicesResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "net": 8700.0, "vat": 1305.0, "gross": 1.0, "currency": "ZAR", "status": "sent", "submittedAt": "2026-09-01T09:15:00Z", "orderNumber": "PO-0001", "lines": [ { "description": "Consulting services — August 2026", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 3.0, "unitPrice": 2900.0, "vatRate": 15.0, "vatInclusive": false, "lineTotal": 10005.0, "vatAmount": 1305.0 } ], "canWithdraw": false, "matchStatus": "sent", "matchNote": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Supplier portal API" ], "summary": "Submit an invoice against an order. It arrives as a bill for the buyer to match, never as an approved payable.", "operationId": "postSupplierApiV1Invoices", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseOrderId": { "type": "string" }, "invoiceNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostSupplierApiV1InvoicesRequestLinesItem" } }, "note": { "type": "string" }, "clientReference": { "type": "string" } } }, "example": { "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "ACME-8841", "issueDate": "2026-09-09", "dueDate": "2026-10-01", "lines": [ { "description": "Consulting services — August 2026", "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "quantity": 500.0, "unitPrice": 81.0, "vatRate": 15.0, "vatInclusive": false, "lineTotal": 10005.0, "vatAmount": 1305.0 } ], "note": "Budget deferred to the next financial year.", "clientReference": "INV-0001" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierApiV1OffersResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostSupplierApiV1OffersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/invoices/{id}/withdraw": { "post": { "tags": [ "Supplier portal API" ], "summary": "Withdraw a submitted invoice before the buyer processes it.", "operationId": "postSupplierApiV1InvoicesByIdWithdraw", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierApiV1OffersResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostSupplierApiV1OffersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/catalogue": { "get": { "tags": [ "Supplier portal API" ], "summary": "The supplier's own price list, and which of their prices the buyer is ordering against.", "operationId": "getSupplierApiV1Catalogue", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "supplierSku": { "type": "string" }, "unit": { "type": "string" }, "unitPrice": { "type": "number" }, "currency": { "type": "string" }, "minOrderQty": { "type": "number" }, "orderMultiple": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "validFrom": { "type": "string", "format": "date" }, "validUntil": { "type": "string", "format": "date" }, "notes": { "type": "string" }, "priceBreaks": { "type": "array", "items": { "$ref": "#/components/schemas/PostSupplierApiV1CatalogueRequestPriceBreaksItem" } }, "buyerProductName": { "type": "string" }, "updatedAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "supplierSku": "LEN-TP-14G4", "unit": "each", "unitPrice": 2900.0, "currency": "ZAR", "minOrderQty": 3.0, "orderMultiple": 1.0, "leadTimeDays": 30, "status": "sent", "statusLabel": "Karoo Fresh Holdings Ltd", "validFrom": "2026-09-01", "validUntil": "2026-09-30", "notes": "Budget deferred to the next financial year.", "priceBreaks": [ { "minQty": 3.0, "unitPrice": 2900.0, "note": "Budget deferred to the next financial year." } ], "buyerProductName": "Karoo Fresh Holdings Ltd", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Supplier portal API" ], "summary": "Add or correct one price-list item. Keyed on the supplier's own SKU, so re-sending a price list updates rather than duplicating.", "operationId": "postSupplierApiV1Catalogue", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "supplierSku": { "type": "string" }, "unit": { "type": "string" }, "unitPrice": { "type": "number" }, "minOrderQty": { "type": "number" }, "orderMultiple": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "validFrom": { "type": "string", "format": "date" }, "validUntil": { "type": "string", "format": "date" }, "notes": { "type": "string" }, "priceBreaks": { "type": "array", "items": { "$ref": "#/components/schemas/PostSupplierApiV1CatalogueRequestPriceBreaksItem" } } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "12mm mild steel plate", "supplierSku": "MS-12-2412", "unit": "each", "unitPrice": 1840.0, "minOrderQty": 4.0, "orderMultiple": 4.0, "leadTimeDays": 5, "validFrom": "2026-09-01", "validUntil": "2026-09-30", "notes": "Budget deferred to the next financial year.", "priceBreaks": [ { "minQty": 20.0, "unitPrice": 1755.0, "note": "Budget deferred to the next financial year." } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierApiV1OffersResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostSupplierApiV1OffersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/catalogue/{id}/withdraw": { "post": { "tags": [ "Supplier portal API" ], "summary": "Stop offering an item. Withdrawn rather than deleted, so a price quoted last month stays explicable.", "operationId": "postSupplierApiV1CatalogueByIdWithdraw", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierApiV1OffersResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostSupplierApiV1OffersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/compliance": { "get": { "tags": [ "Supplier portal API" ], "summary": "What is on file, what is about to lapse, and what the buyer has never had — the missing list included, because a supplier cannot send a document nobody asked for.", "operationId": "getSupplierApiV1Compliance", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1ComplianceResponseMissingItem" } }, "missing": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1ComplianceResponseMissingItem" } }, "bbbeeSpendClaimable": { "type": "boolean" }, "attention": { "type": "array", "items": { "type": "string" } } } }, "example": { "documents": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "invoice", "kindLabel": "Karoo Fresh Holdings Ltd", "consequence": "text", "reference": "INV-0001", "issuedOn": "2026-09-01", "expiresOn": "2026-09-01", "state": "sent", "stateLabel": "Karoo Fresh Holdings Ltd", "daysUntilExpiry": 30, "claimedBbbeeLevel": 1, "reviewNote": "Budget deferred to the next financial year.", "fileUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "submittedAt": "2026-09-01T09:15:00Z" } ], "missing": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "invoice", "kindLabel": "Karoo Fresh Holdings Ltd", "consequence": "text", "reference": "INV-0001", "issuedOn": "2026-09-01", "expiresOn": "2026-09-01", "state": "sent", "stateLabel": "Karoo Fresh Holdings Ltd", "daysUntilExpiry": 30, "claimedBbbeeLevel": 1, "reviewNote": "Budget deferred to the next financial year.", "fileUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "submittedAt": "2026-09-01T09:15:00Z" } ], "bbbeeSpendClaimable": false, "attention": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Supplier portal API" ], "summary": "File a compliance document. It arrives as submitted and changes nothing until a person accepts it; a B-BBEE level is held as a CLAIM until then.", "operationId": "postSupplierApiV1Compliance", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "reference": { "type": "string" }, "issuedOn": { "type": "string", "format": "date" }, "expiresOn": { "type": "string", "format": "date" }, "claimedBbbeeLevel": { "type": "integer" }, "claimedBlackOwnedPercent": { "type": "number" }, "claimedBlackWomanOwnedPercent": { "type": "number" }, "claimedIsEme": { "type": "boolean" }, "claimedIsQse": { "type": "boolean" }, "attachmentId": { "type": "string" } } }, "example": { "kind": "bbbee_certificate", "reference": "VA-2026-00184", "issuedOn": "2026-03-01", "expiresOn": "2027-02-28", "claimedBbbeeLevel": 4, "claimedBlackOwnedPercent": 15.0, "claimedBlackWomanOwnedPercent": 15.0, "claimedIsEme": false, "claimedIsQse": false, "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierApiV1OffersResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostSupplierApiV1OffersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/registration": { "get": { "tags": [ "Supplier portal API" ], "summary": "The supplier self-registration form: whose link it is, their note, and the documents they require. Carries the registration link's token as a bearer header.", "operationId": "getSupplierApiV1Registration", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "buyerName": { "type": "string" }, "intro": { "type": "string" }, "requiredDocuments": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1RegistrationResponseOptionalDocumentsItem" } }, "optionalDocuments": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1RegistrationResponseOptionalDocumentsItem" } }, "maxDocumentBytes": { "type": "integer" } } }, "example": { "buyerName": "Karoo Fresh Holdings Ltd", "intro": "text", "requiredDocuments": [ { "kind": "invoice", "label": "Karoo Fresh Holdings Ltd", "expires": true, "consequence": "text" } ], "optionalDocuments": [ { "kind": "invoice", "label": "Karoo Fresh Holdings Ltd", "expires": true, "consequence": "text" } ], "maxDocumentBytes": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Supplier portal API" ], "summary": "Send a supplier registration: company details, VAT and CIPC numbers, a contact, and the uploaded documents. No bank details are taken. It changes nothing until the business accepts it.", "operationId": "postSupplierApiV1Registration", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tradingName": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "companyName": { "type": "string" }, "registrationNumber": { "type": "string" }, "vatNumber": { "type": "string" }, "contactName": { "type": "string" }, "email": { "type": "string" }, "supplies": { "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "attachmentId": { "type": "string" }, "reference": { "type": "string" }, "expiresOn": { "type": "string", "format": "date" } } } } } }, "example": { "tradingName": "Karoo Gas Supplies", "phone": "+27 21 555 0142", "address": "14 Voortrekker Road, Bellville, 7530", "companyName": "Steelco (Pty) Ltd", "registrationNumber": "2019/123456/07", "vatNumber": "4123456784", "contactName": "Thandi Mokoena", "email": "tenders@steelco.example", "supplies": "Steel plate and sections", "documents": [ { "kind": "tax_clearance", "attachmentId": "22e0b355-9548-5a94-bdda-2c708df386f5", "reference": "TCS-0042", "expiresOn": "2027-03-31" } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string" }, "message": { "type": "string" } } }, "example": { "reference": "INV-0001", "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/registration/upload": { "post": { "tags": [ "Supplier portal API" ], "summary": "Upload the scan of one document for a registration, up to 8MB. Returns an attachment id to quote on the application. The server decides the content type, never the client.", "operationId": "postSupplierApiV1RegistrationUpload", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachmentId": { "type": "string" }, "sizeBytes": { "type": "integer" } } }, "example": { "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sizeBytes": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/compliance/upload": { "post": { "tags": [ "Supplier portal API" ], "summary": "Upload the scan of a document, up to 8MB. Returns an attachment id to quote on the submit. The server decides the content type, never the client.", "operationId": "postSupplierApiV1ComplianceUpload", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachmentId": { "type": "string" }, "sizeBytes": { "type": "string" } } }, "example": { "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sizeBytes": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/offers": { "get": { "tags": [ "Supplier portal API" ], "summary": "Offers this supplier has made unasked, with the buyer's outcome and whether each may still be revised.", "operationId": "getSupplierApiV1Offers", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "quoteNumber": { "type": "string" }, "quoteDate": { "type": "string", "format": "date" }, "validUntil": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "paymentTermsDays": { "type": "integer" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "revision": { "type": "integer" }, "withdrawn": { "type": "boolean" }, "outcomeNote": { "type": "string" }, "canRevise": { "type": "boolean" }, "revisionRefusal": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1OffersResponseItemLinesItem" } }, "notes": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "title": "Karoo Fresh Holdings Ltd", "quoteNumber": "INV-0001", "quoteDate": "2026-09-01", "validUntil": "2026-09-30", "currency": "ZAR", "net": 8700.0, "vat": 1305.0, "gross": 1.0, "leadTimeDays": 30, "paymentTermsDays": 30, "status": "sent", "statusLabel": "Karoo Fresh Holdings Ltd", "revision": 1, "withdrawn": false, "outcomeNote": "Budget deferred to the next financial year.", "canRevise": false, "revisionRefusal": "text", "lines": [ { "rfqLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "quantity": 3.0, "unitPrice": 2900.0, "leadTimeDays": 30, "notes": "Budget deferred to the next financial year.", "lineTotal": 10005.0 } ], "notes": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Supplier portal API" ], "summary": "Send a price nobody asked for, or revise one already sent. Idempotent on clientReference — two prices for the same work in front of a buyer is worse than a duplicate invoice.", "operationId": "postSupplierApiV1Offers", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientReference": { "type": "string" }, "title": { "type": "string" }, "quoteNumber": { "type": "string" }, "validUntil": { "type": "string", "format": "date" }, "leadTimeDays": { "type": "integer" }, "paymentTermsDays": { "type": "integer" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "vatRatePercent": { "type": "number" }, "vatInclusive": { "type": "boolean" }, "discountPercent": { "type": "number" }, "supplierSku": { "type": "string" }, "unit": { "type": "string" }, "minOrderQty": { "type": "number" }, "leadTimeDays": { "type": "integer" } } } }, "revisesQuoteId": { "type": "string" } } }, "example": { "clientReference": "offer-4471", "title": "Steelwork, Bellville warehouse", "quoteNumber": "INV-0001", "validUntil": "2026-10-15", "leadTimeDays": 10, "paymentTermsDays": 30, "notes": "Budget deferred to the next financial year.", "lines": [ { "description": "Portal frames", "quantity": 40.0, "unitPrice": 8750.0, "vatRatePercent": 15.0, "vatInclusive": false, "discountPercent": 0.0, "supplierSku": "LEN-TP-14G4", "unit": "each", "minOrderQty": 3.0, "leadTimeDays": 30 } ], "revisesQuoteId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierApiV1OffersResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostSupplierApiV1OffersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/offers/{id}/withdraw": { "post": { "tags": [ "Supplier portal API" ], "summary": "Take an offer off the table. A different fact from the buyer rejecting it, so it does not overwrite the status.", "operationId": "postSupplierApiV1OffersByIdWithdraw", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierApiV1OffersResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostSupplierApiV1OffersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/orders/{id}/despatchable": { "get": { "tags": [ "Supplier portal API" ], "summary": "What may still be declared as sent on an order — netting off what has been received AND what is already in transit.", "operationId": "getSupplierApiV1OrdersByIdDespatchable", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "poLineId": { "type": "string" }, "description": { "type": "string" }, "qtyOrdered": { "type": "number" }, "qtyReceived": { "type": "number" }, "qtyAlreadyDespatched": { "type": "number" }, "qtyRemaining": { "type": "number" }, "unit": { "type": "string" } } } }, "example": [ { "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyOrdered": 1.0, "qtyReceived": 1.0, "qtyAlreadyDespatched": 1.0, "qtyRemaining": 1.0, "unit": "each" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/orders/{id}/despatch": { "post": { "tags": [ "Supplier portal API" ], "summary": "Declare that goods have left. Moves no stock and costs nothing; it pre-fills the buyer's goods receipt and gives their expediting screen a real arrival date.", "operationId": "postSupplierApiV1OrdersByIdDespatch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientReference": { "type": "string" }, "despatchedOn": { "type": "string", "format": "date" }, "expectedArrival": { "type": "string", "format": "date" }, "carrier": { "type": "string" }, "waybill": { "type": "string" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "poLineId": { "type": "string" }, "qty": { "type": "number" } } } } } }, "example": { "clientReference": "asn-9912", "despatchedOn": "2026-09-10", "expectedArrival": "2026-09-12", "carrier": "Own vehicle", "waybill": "WB-33417", "notes": "Budget deferred to the next financial year.", "lines": [ { "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qty": 40.0 } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierApiV1OffersResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostSupplierApiV1OffersResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/despatches": { "get": { "tags": [ "Supplier portal API" ], "summary": "Deliveries this supplier has declared, and whether each has been booked in.", "operationId": "getSupplierApiV1Despatches", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "orderNumber": { "type": "string" }, "despatchedOn": { "type": "string", "format": "date" }, "expectedArrival": { "type": "string" }, "carrier": { "type": "string" }, "waybill": { "type": "string" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1DespatchesResponseItemLinesItem" } }, "complete": { "type": "boolean" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "orderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "orderNumber": "PO-0001", "despatchedOn": "2026-09-01", "expectedArrival": "text", "carrier": "text", "waybill": "text", "status": "sent", "statusLabel": "Karoo Fresh Holdings Ltd", "notes": "Budget deferred to the next financial year.", "lines": [ { "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0 } ], "complete": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/statement": { "get": { "tags": [ "Supplier portal API" ], "summary": "What the supplier is owed, when it falls due, and the payables control's verdict on anything held — from the buyer's own books.", "operationId": "getSupplierApiV1Statement", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "awaitingAcceptance": { "type": "number" }, "notYetDue": { "type": "number" }, "overdue": { "type": "number" }, "paidLast90Days": { "type": "number" }, "nextDueDate": { "type": "string", "format": "date" }, "nextDueAmount": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "reference": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "gross": { "type": "number" }, "status": { "type": "string" }, "positionLabel": { "type": "string" }, "daysUntilDue": { "type": "integer" }, "matchStatus": { "type": "string" }, "matchNote": { "type": "string" } } } } } }, "example": { "currency": "ZAR", "awaitingAcceptance": 1.0, "notYetDue": 1.0, "overdue": 1.0, "paidLast90Days": 1.0, "nextDueDate": "2026-09-01", "nextDueAmount": 10005.0, "lines": [ { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "gross": 1.0, "status": "sent", "positionLabel": "Karoo Fresh Holdings Ltd", "daysUntilDue": 30, "matchStatus": "sent", "matchNote": "Budget deferred to the next financial year." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-api/v1/scorecard": { "get": { "tags": [ "Supplier portal API" ], "summary": "The supplier's own on-time rating, quote win rate and spend. The same figures the buyer's vendor list draws — a rating a supplier cannot see is one they cannot improve.", "operationId": "getSupplierApiV1Scorecard", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveriesScored": { "type": "integer" }, "onTimeDeliveries": { "type": "integer" }, "onTimePercent": { "type": "integer" }, "quotesSubmitted": { "type": "integer" }, "quotesWon": { "type": "integer" }, "winRatePercent": { "type": "integer" }, "spendLast12Months": { "type": "number" }, "currency": { "type": "string" }, "openOrders": { "type": "integer" }, "openOrderValue": { "type": "number" } } }, "example": { "deliveriesScored": 1, "onTimeDeliveries": 1, "onTimePercent": 15, "quotesSubmitted": 1, "quotesWon": 1, "winRatePercent": 15, "spendLast12Months": 1.0, "currency": "ZAR", "openOrders": 1, "openOrderValue": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/supplier-offers": { "get": { "tags": [ "Supplier workspace, buyer side" ], "summary": "Quotes suppliers sent without being asked. Kept apart from RFQ responses, which belong beside their competitors.", "operationId": "getApiProcurementSupplierOffers", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "includeClosed", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "title": { "type": "string" }, "quoteNumber": { "type": "string" }, "quoteDate": { "type": "string", "format": "date" }, "validUntil": { "type": "string", "format": "date" }, "expired": { "type": "boolean" }, "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "paymentTermsDays": { "type": "integer" }, "status": { "type": "string" }, "revision": { "type": "integer" }, "withdrawnBySupplier": { "type": "boolean" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "supplierSku": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "unitPrice": { "type": "number" }, "vatRate": { "type": "number" }, "discountRate": { "type": "number" }, "lineTotal": { "type": "number" }, "minOrderQty": { "type": "number" }, "leadTimeDays": { "type": "integer" } } } } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "title": "Karoo Fresh Holdings Ltd", "quoteNumber": "INV-0001", "quoteDate": "2026-09-01", "validUntil": "2026-09-30", "expired": false, "net": 8700.0, "vat": 1305.0, "gross": 1.0, "leadTimeDays": 30, "paymentTermsDays": 30, "status": "sent", "revision": 1, "withdrawnBySupplier": false, "notes": "Budget deferred to the next financial year.", "lines": [ { "description": "Consulting services — August 2026", "supplierSku": "LEN-TP-14G4", "quantity": 3.0, "unit": "each", "unitPrice": 2900.0, "vatRate": 15.0, "discountRate": 0.0, "lineTotal": 10005.0, "minOrderQty": 3.0, "leadTimeDays": 30 } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/supplier-offers/{id}/decide": { "post": { "tags": [ "Supplier workspace, buyer side" ], "summary": "Accept or decline an offer. A reason is required on a decline and the supplier reads it — 'we went elsewhere' with no reason is why suppliers stop quoting.", "operationId": "postApiProcurementSupplierOffersByIdDecide", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiProcurementSupplierOffersByIdDecideRequest" }, "example": { "outcome": "decline", "note": "Went with a shorter lead time." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiProcurementSupplierOffersByIdDecideResponse" }, "example": { "ok": "true", "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/supplier-catalogue": { "get": { "tags": [ "Supplier workspace, buyer side" ], "summary": "What suppliers say they sell, with their volume breaks and order multiples.", "operationId": "getApiProcurementSupplierCatalogue", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "supplierId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "active" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "description": { "type": "string" }, "supplierSku": { "type": "string" }, "unit": { "type": "string" }, "unitPrice": { "type": "number" }, "currency": { "type": "string" }, "minOrderQty": { "type": "number" }, "orderMultiple": { "type": "number" }, "leadTimeDays": { "type": "integer" }, "status": { "type": "string" }, "productId": { "type": "string" }, "priceBreaks": { "type": "array", "items": { "type": "object", "properties": { "minQty": { "type": "number" }, "unitPrice": { "type": "number" } } } }, "validFrom": { "type": "string", "format": "date" }, "validUntil": { "type": "string", "format": "date" }, "notes": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "supplierSku": "LEN-TP-14G4", "unit": "each", "unitPrice": 2900.0, "currency": "ZAR", "minOrderQty": 3.0, "orderMultiple": 1.0, "leadTimeDays": 30, "status": "sent", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "priceBreaks": [ { "minQty": 3.0, "unitPrice": 2900.0 } ], "validFrom": "2026-09-01", "validUntil": "2026-09-30", "notes": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/supplier-catalogue/{id}/adopt": { "post": { "tags": [ "Supplier workspace, buyer side" ], "summary": "Take an offered item into the approved source list. COPIES the figures, so a supplier editing their catalogue afterwards cannot move a price you have contracted at.", "operationId": "postApiProcurementSupplierCatalogueByIdAdopt", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiProcurementSupplierOffersByIdDecideResponse" }, "example": { "ok": "true", "message": "$out is now an approved source at the supplier's price." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/supplier-compliance": { "get": { "tags": [ "Supplier workspace, buyer side" ], "summary": "Every supplier's paperwork with its expiry and what lapses with it — the 30-day question is a WHERE clause on one date.", "operationId": "getApiProcurementSupplierCompliance", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "kind": { "type": "string" }, "kindLabel": { "type": "string" }, "consequence": { "type": "string" }, "reference": { "type": "string" }, "issuedOn": { "type": "string", "format": "date" }, "expiresOn": { "type": "string", "format": "date" }, "daysUntilExpiry": { "type": "integer" }, "state": { "type": "string" }, "status": { "type": "string" }, "claimedBbbeeLevel": { "type": "integer" }, "submittedBySupplier": { "type": "boolean" }, "submittedAt": { "type": "string" }, "fileId": { "type": "string" }, "reviewNote": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "kind": "invoice", "kindLabel": "Karoo Fresh Holdings Ltd", "consequence": "text", "reference": "INV-0001", "issuedOn": "2026-09-01", "expiresOn": "2026-09-01", "daysUntilExpiry": 30, "state": "sent", "status": "sent", "claimedBbbeeLevel": 1, "submittedBySupplier": false, "submittedAt": "2026-09-01T09:15:00Z", "fileId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reviewNote": "Budget deferred to the next financial year." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/supplier-compliance/{id}/review": { "post": { "tags": [ "Supplier workspace, buyer side" ], "summary": "Accept or reject a document. Accepting a B-BBEE certificate is the ONLY thing that writes contacts.bbbee_level, because an unverified level is an audit finding against the buyer who claimed the spend.", "operationId": "postApiProcurementSupplierComplianceByIdReview", "description": "Requires the `procurement:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiProcurementSupplierOffersByIdDecideRequest" }, "example": { "outcome": "accept", "note": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiProcurementSupplierOffersByIdDecideResponse" }, "example": { "ok": "true", "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/procurement/incoming-despatches": { "get": { "tags": [ "Supplier workspace, buyer side" ], "summary": "What suppliers say is on its way, with a real expected arrival rather than a date typed at ordering time. Nothing here has moved any stock.", "operationId": "getApiProcurementIncomingDespatches", "description": "Requires the `procurement:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "procurement:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "includeReceived", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "orderNumber": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "despatchedOn": { "type": "string", "format": "date" }, "expectedArrival": { "type": "string" }, "daysUntilArrival": { "type": "integer" }, "carrier": { "type": "string" }, "waybill": { "type": "string" }, "status": { "type": "string" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetSupplierApiV1DespatchesResponseItemLinesItem" } } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "orderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "orderNumber": "PO-0001", "supplierId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supplierName": "Karoo Fresh Holdings Ltd", "despatchedOn": "2026-09-01", "expectedArrival": "text", "daysUntilArrival": 30, "carrier": "text", "waybill": "text", "status": "sent", "notes": "Budget deferred to the next financial year.", "lines": [ { "poLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qty": 3.0 } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/vehicles/{id}/fuel": { "get": { "tags": [ "Logistics & fleet" ], "summary": "A vehicle's fill-ups, newest first, with its consumption measured fill to fill and a sentence when that has jumped.", "operationId": "getApiLogisticsVehiclesByIdFuel", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "vehicleId": { "type": "string" }, "registration": { "type": "string" }, "litresPer100Km": { "type": "number" }, "warning": { "type": "string" }, "fills": { "type": "array", "items": { "$ref": "#/components/schemas/PostDriverApiV1FuelResponse" } } } }, "example": { "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registration": "text", "litresPer100Km": 1.0, "warning": "text", "fills": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "filledOn": "2026-09-01", "litres": 1.0, "amount": 10005.0, "odometerKm": 1.0, "garage": "text", "cardRef": "INV-0001", "source": "referral", "expenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/fuel": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Record a fill-up. Posts one zero-rated fuel expense; links to the vehicle's trip that day. Send clientReference and a retry lands once.", "operationId": "postApiLogisticsFuel", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1FuelRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostDriverApiV1FuelRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1FuelResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostDriverApiV1FuelResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/fuel/import": { "post": { "tags": [ "Logistics & fleet" ], "summary": "A fuel-card statement pasted as text; columns are found by their headings (date, registration, litres, amount, odometer, merchant, card). Each line lands once; every line that could not is named by its number.", "operationId": "postApiLogisticsFuelImport", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" } } }, "example": { "text": "date,registration,litres,amount,odometer,merchant,card\n2026-09-01,CA 123-456,62.4,1310.40,184320,Rivonia Road service station,FC-4471\n2026-09-03,CA 123-456,58.1,1220.10,184905,N1 Kraaifontein fuel stop,FC-4471" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "recorded": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object" } } } }, "example": { "recorded": 1, "problems": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/settings": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The company's Logistics settings: the number drivers reach the office on, and the company phone they reach when it is not set.", "operationId": "getApiLogisticsSettings", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsSettingsResponse" }, "example": { "officePhone": "+27 82 555 0143", "companyPhone": "+27 82 555 0143" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Logistics & fleet" ], "summary": "Set the number drivers reach the office on (null or blank falls back to the company's phone). Refused unless it can be a phone number.", "operationId": "putApiLogisticsSettings", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "officePhone": { "type": "string" } } }, "example": { "officePhone": "011 555 0100" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsSettingsResponse" }, "example": { "officePhone": "+27 82 555 0143", "companyPhone": "+27 82 555 0143" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/tracking/settings": { "get": { "tags": [ "Logistics & fleet" ], "summary": "How fresh the live map is: while a trip is running, each driver's phone sends its position every flushSeconds (60 to 120). Needs the Driver-tracking add-on.", "operationId": "getApiLogisticsTrackingSettings", "description": "Requires the `driver-tracking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "driver-tracking:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsTrackingSettingsResponse" }, "example": { "flushSeconds": 120, "minSeconds": 60, "maxSeconds": 120 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Logistics & fleet" ], "summary": "Choose how often a phone on a running trip sends its position, 60 to 120 seconds. Outside a trip nothing is sent, whatever this says. Needs the Driver-tracking add-on.", "operationId": "putApiLogisticsTrackingSettings", "description": "Requires the `driver-tracking:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "driver-tracking:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "flushSeconds": { "type": "integer" } } }, "example": { "flushSeconds": 60 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsTrackingSettingsResponse" }, "example": { "flushSeconds": 60, "minSeconds": 60, "maxSeconds": 120 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/dispatch": { "get": { "tags": [ "Logistics & fleet" ], "summary": "One day on the dispatch board: a lane per vehicle with the trip it is on that day, what that trip carries against the vehicle, and whether a load may be dropped on it; and the loads waiting: those due at the door on or before the day (overdue first, then by customer), a page of 100 with waitingTotal beside it, ?waitingPage=n for the next; and the loads with no delivery date apart (undated, undatedTotal). ?date=yyyy-MM-dd, today in South Africa when absent.", "operationId": "getApiLogisticsDispatch", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "waitingPage", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "lanes": { "type": "array", "items": { "type": "object", "properties": { "vehicleId": { "type": "string" }, "registration": { "type": "string" }, "fleetNumber": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "tripStatus": { "type": "string" }, "driverName": { "type": "string" }, "stops": { "type": "array", "items": { "type": "object", "properties": { "stopId": { "type": "string" }, "sequence": { "type": "integer" }, "label": { "type": "string" }, "documentNumber": { "type": "string" } } } }, "load": { "$ref": "#/components/schemas/PostApiLogisticsTripsResponseLoad" }, "acceptsLoads": { "type": "boolean" }, "note": { "type": "string" } } } }, "waiting": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsUnassignedResponseItem" } }, "waitingTotal": { "type": "integer" }, "waitingPage": { "type": "integer" }, "undated": { "type": "array", "items": { "type": "object", "properties": { "documentId": { "type": "string" }, "documentNumber": { "type": "string" }, "documentType": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "address": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "lineCount": { "type": "integer" }, "totalQty": { "type": "number" }, "total": { "type": "number" }, "currency": { "type": "string" } } } }, "undatedTotal": { "type": "integer" } } }, "example": { "date": "2026-09-01", "lanes": [ { "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registration": "text", "fleetNumber": "INV-0001", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "tripStatus": "sent", "driverName": "Thandi Mokoena", "stops": [ { "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sequence": 1, "label": "Karoo Fresh Holdings Ltd", "documentNumber": "INV-0001" } ], "load": { "weightKg": 1.0, "volumeM3": 1.0, "pallets": 1, "payloadKg": 1.0, "vehicleVolumeM3": 1.0, "vehiclePallets": 1, "linesWithoutWeight": 1, "warnings": [] }, "acceptsLoads": true, "note": "Budget deferred to the next financial year." } ], "waiting": [ { "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "documentType": "invoice", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "issueDate": "2026-09-01", "deliveryDate": "2026-09-01", "address": "12 Long Street, Cape Town, 8001", "city": "Cape Town", "postalCode": "CT-001", "lineCount": 3, "totalQty": 3.0, "total": 10005.0, "currency": "ZAR" } ], "waitingTotal": 42, "waitingPage": 1, "undated": [ { "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "documentType": "invoice", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "issueDate": "2026-09-01", "address": "12 Long Street, Cape Town, 8001", "city": "Cape Town", "postalCode": "CT-001", "lineCount": 3, "totalQty": 3.0, "total": 10005.0, "currency": "ZAR" } ], "undatedTotal": 42 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/stops/{id}/location": { "put": { "tags": [ "Logistics & fleet" ], "summary": "Place a stop at a point the office chose — typed coordinates or a pasted map link. With saveToContact (the default) the point also becomes the contact's delivery location, so the next stop built there carries it. A stop with an outcome is part of the record and cannot be moved.", "operationId": "putApiLogisticsStopsByIdLocation", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "saveToContact": { "type": "boolean" } } }, "example": { "latitude": -29.8587, "longitude": 31.0218, "saveToContact": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLogisticsStopsByIdLocationResponse" }, "examples": { "default": { "$ref": "#/components/examples/PutApiLogisticsStopsByIdLocationResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/proofs/{id}/learn-location": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Save the fix a driver's phone took with this proof as the contact's delivery location. Offered, never automatic: only a fix the phone claimed to within 100 m, and never over a location a person placed.", "operationId": "postApiLogisticsProofsByIdLearnLocation", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLogisticsStopsByIdLocationResponse" }, "examples": { "default": { "$ref": "#/components/examples/PutApiLogisticsStopsByIdLocationResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/geocode": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Candidate points for a street address, for a person to choose one and place it. Nothing is stored. Refused when street maps are not configured on this deployment; every lookup is a billed call, so it needs edit permission.", "operationId": "postApiLogisticsGeocode", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiCrmBccAddressResponse" }, "example": { "address": "12 Smith Street, Durban" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "approximate": { "type": "boolean" } } } } } }, "example": { "candidates": [ { "label": "Karoo Fresh Holdings Ltd", "latitude": 1.0, "longitude": 1.0, "approximate": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/compliance/expiring": { "get": { "tags": [ "Logistics & fleet" ], "summary": "Licences and discs expiring: every licence disc, roadworthy, operator card, driving licence and PrDP at or inside its 60-day reminder (60, 30, 7 and 0 days), expired first, with whether the list can be emailed and why not.", "operationId": "getApiLogisticsComplianceExpiring", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "type": "string" }, "horizonDays": { "type": "integer" }, "summary": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "holder": { "type": "string" }, "holderId": { "type": "string" }, "holderName": { "type": "string" }, "document": { "type": "string" }, "documentLabel": { "type": "string" }, "expiresOn": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "stage": { "type": "string" }, "stageLabel": { "type": "string" }, "sentence": { "type": "string" } } } }, "emailAvailable": { "type": "boolean" }, "emailBlockedReason": { "type": "string" } } }, "example": { "asOf": "text", "horizonDays": 30, "summary": "Consulting services — August 2026", "items": [ { "holder": "vehicle", "holderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "holderName": "Karoo Fresh Holdings Ltd", "document": "text", "documentLabel": "Karoo Fresh Holdings Ltd", "expiresOn": "2026-09-01", "days": 30, "stage": "text", "stageLabel": "Karoo Fresh Holdings Ltd", "sentence": "text" } ], "emailAvailable": false, "emailBlockedReason": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/compliance/expiring/email": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Email the expiring list to the fleet controllers (users whose role edits Logistics) and the owner, now. On demand only; refused in words when the notification switch is off, email is not set up, nothing is due or nobody can receive it.", "operationId": "postApiLogisticsComplianceExpiringEmail", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "integer" }, "recipients": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } } }, "example": { "sent": 1, "recipients": [ "text" ], "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/servicing": { "get": { "tags": [ "Logistics & fleet" ], "summary": "Every vehicle still on the fleet against its service plan (every N km or N months, whichever first): last service, next due by distance and date, and a sentence saying where it stands.", "operationId": "getApiLogisticsServicing", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsServicingResponseItem" } }, "example": [ { "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registration": "text", "everyKm": 1, "everyMonths": 1, "standingCostPerKm": 10005.0, "odometerKm": 1.0, "lastServiceOn": "2026-09-01", "lastServiceKm": 1.0, "state": "sent", "stateLabel": "Karoo Fresh Holdings Ltd", "dueAtKm": 1.0, "dueOn": "2026-09-01", "kmLeft": 1.0, "daysLeft": 30, "estimatedOn": "2026-09-01", "sentence": "text" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/vehicles/{id}/service": { "get": { "tags": [ "Logistics & fleet" ], "summary": "A vehicle's service sheet: its plan, its service log, what it cost this year (every purchase allocated to it that reached the ledger, fuel included) and those purchases.", "operationId": "getApiLogisticsVehiclesByIdService", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/GetApiLogisticsServicingResponseItem" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLogisticsVehicleServicesResponse" } }, "costThisYear": { "type": "number" }, "purchases": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amountExVat": { "type": "number" }, "linkedToService": { "type": "boolean" } } } } } }, "example": { "plan": { "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registration": "text", "everyKm": 1, "everyMonths": 1, "standingCostPerKm": 10005.0, "odometerKm": 1.0, "lastServiceOn": "2026-09-01", "lastServiceKm": 1.0, "state": "sent", "stateLabel": "Karoo Fresh Holdings Ltd", "dueAtKm": 1.0, "dueOn": "2026-09-01", "kmLeft": 1.0, "daysLeft": 30, "estimatedOn": "2026-09-01", "sentence": "text" }, "entries": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "serviceOn": "2026-09-01", "odometerKm": 1.0, "kind": "standard", "kindLabel": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "expenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseLabel": "Karoo Fresh Holdings Ltd", "costExVat": 1305.0, "inspectionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "costThisYear": 10005.0, "purchases": [ { "kind": "expense", "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "amountExVat": 1305.0, "linkedToService": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/vehicles/{id}/service-plan": { "put": { "tags": [ "Logistics & fleet" ], "summary": "Set a vehicle's service plan and its standing cost per km. Blank clears; both intervals blank is no plan.", "operationId": "putApiLogisticsVehiclesByIdServicePlan", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "everyKm": { "type": "integer" }, "everyMonths": { "type": "integer" }, "standingCostPerKm": { "type": "number" }, "costPerKmIncludesFuel": { "type": "boolean" } } }, "example": { "everyKm": 15000, "everyMonths": 12, "standingCostPerKm": 2.35, "costPerKmIncludesFuel": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsServicingResponseItem" }, "example": { "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registration": "text", "everyKm": 1, "everyMonths": 1, "standingCostPerKm": 10005.0, "odometerKm": 1.0, "lastServiceOn": "2026-09-01", "lastServiceKm": 1.0, "state": "sent", "stateLabel": "Karoo Fresh Holdings Ltd", "dueAtKm": 1.0, "dueOn": "2026-09-01", "kmLeft": 1.0, "daysLeft": 30, "estimatedOn": "2026-09-01", "sentence": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/vehicle-services": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Log a service, repair or tyres. Either links a purchase already allocated to the vehicle or records the workshop's invoice here as an ordinary expense on the vehicle; never both. The odometer reading moves the vehicle's forward. Send clientReference and a retry lands once.", "operationId": "postApiLogisticsVehicleServices", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vehicleId": { "type": "string" }, "serviceOn": { "type": "string", "format": "date" }, "odometerKm": { "type": "number" }, "kind": { "type": "string" }, "description": { "type": "string" }, "costExVat": { "type": "number" }, "vatCharged": { "type": "boolean" }, "supplier": { "type": "string" }, "expenseId": { "type": "string" }, "billId": { "type": "string" }, "inspectionId": { "type": "string" }, "clientReference": { "type": "string" } } }, "example": { "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "serviceOn": "2026-09-01", "odometerKm": 1.0, "kind": "service", "description": "Consulting services — August 2026", "costExVat": 1305.0, "vatCharged": true, "supplier": "Karoo Fresh Holdings Ltd", "expenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "inspectionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientReference": "INV-0001" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsVehicleServicesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "serviceOn": "2026-09-01", "odometerKm": 1.0, "kind": "standard", "kindLabel": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "expenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseLabel": "Karoo Fresh Holdings Ltd", "costExVat": 1305.0, "inspectionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/inspection-checklist": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The company's pre-trip checklist, in order, and the standard list it can start from. Empty means drivers are asked nothing.", "operationId": "getApiLogisticsInspectionChecklist", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsInspectionChecklistResponse" }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd" } ], "standard": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Logistics & fleet" ], "summary": "Replace the pre-trip checklist, in order. An empty list switches the check off; answers already given keep the wording the driver read.", "operationId": "putApiLogisticsInspectionChecklist", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string" } } } }, "example": { "labels": [ "Tyres and wheel nuts", "Lights and indicators", "Brakes" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsInspectionChecklistResponse" }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd" } ], "standard": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}/inspections": { "get": { "tags": [ "Logistics & fleet" ], "summary": "A trip's pre-trip checks as the driver answered them, newest first: each answer with the wording read, what failed, and the office's decision.", "operationId": "getApiLogisticsTripsByIdInspections", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsTripsByIdInspectionsResponseItem" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "driverName": "Thandi Mokoena", "state": "sent", "stateLabel": "Karoo Fresh Holdings Ltd", "answers": [ { "itemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "passed": true, "note": "Budget deferred to the next financial year." } ], "failedItems": [ "text" ], "capturedAt": "2026-09-01T09:15:00Z", "recordedAt": "2026-09-01T09:15:00Z", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}/inspection/decision": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Answer a failed pre-trip check: allow (the trip may start and the vehicle returns to the road) or keep_off_road (the vehicle stays In for repair; the trip needs another vehicle).", "operationId": "postApiLogisticsTripsByIdInspectionDecision", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string" } } }, "example": { "decision": "allow" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsTripsByIdInspectionsResponseItem" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "driverName": "Thandi Mokoena", "state": "sent", "stateLabel": "Karoo Fresh Holdings Ltd", "answers": [ { "itemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "passed": true, "note": "Budget deferred to the next financial year." } ], "failedItems": [ "text" ], "capturedAt": "2026-09-01T09:15:00Z", "recordedAt": "2026-09-01T09:15:00Z", "decidedAt": "2026-09-01T09:15:00Z", "decidedByName": "Thandi Mokoena" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}/cost": { "get": { "tags": [ "Logistics & fleet" ], "summary": "What a run cost: fuel (its fills), purchases allocated to the trip, driver hours at each driver's cost per hour and the vehicle's standing cost per km; cost per km and per drop; the stops' delivery charges and the margin; and in words, any part that could not be counted.", "operationId": "getApiLogisticsTripsByIdCost", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsCostsResponseRunsItem" }, "examples": { "default": { "$ref": "#/components/examples/GetApiLogisticsTripsByIdCostResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/costs": { "get": { "tags": [ "Logistics & fleet" ], "summary": "Every run in the period with its cost, and the period's cost per km, per drop and margin. ?from&to=yyyy-MM-dd, the last 30 days when absent.", "operationId": "getApiLogisticsCosts", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "fromDate": { "type": "string", "format": "date" }, "toDate": { "type": "string", "format": "date" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsCostsResponseRunsItem" } }, "total": { "type": "number" }, "distanceKm": { "type": "number" }, "drops": { "type": "integer" }, "perKm": { "type": "number" }, "perDrop": { "type": "number" }, "revenue": { "type": "number" }, "margin": { "type": "number" }, "incompleteRuns": { "type": "integer" } } }, "example": { "fromDate": "2026-09-01", "toDate": "2026-09-01", "runs": [ { "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "tripDate": "2026-09-01", "status": "sent", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "distanceKm": 1.0, "drops": 1, "driverHours": 3.0, "fuel": 1.0, "other": 1.0, "labour": 1.0, "standing": 1.0, "total": 10005.0, "perKm": 1.0, "perDrop": 1.0, "revenue": 1.0, "margin": 1.0, "marginPercent": 15.0, "gaps": [ "text" ], "lines": [ { "kind": "fuel", "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0 } ], "stops": [ { "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sequence": 1, "name": "Karoo Fresh Holdings Ltd", "status": "sent", "charge": 1.0 } ] } ], "total": 10005.0, "distanceKm": 1.0, "drops": 1, "perKm": 1.0, "perDrop": 1.0, "revenue": 1.0, "margin": 1.0, "incompleteRuns": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}/costs": { "post": { "tags": [ "Logistics & fleet" ], "summary": "A cost paid on the run — a toll, parking, a tyre — recorded as an ordinary expense on the trip and its vehicle, posted like any other. clientId becomes the expense id, so a retry lands once.", "operationId": "postApiLogisticsTripsByIdCosts", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" }, "amountExVat": { "type": "number" }, "vatCharged": { "type": "boolean" }, "date": { "type": "string", "format": "date" }, "clientId": { "type": "string" } } }, "example": { "description": "Consulting services — August 2026", "amountExVat": 1305.0, "vatCharged": false, "date": "2026-09-01", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsCostsResponseRunsItem" }, "examples": { "default": { "$ref": "#/components/examples/GetApiLogisticsTripsByIdCostResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/stops/{id}/charge": { "put": { "tags": [ "Logistics & fleet" ], "summary": "What the customer is charged for this drop, for the run's margin. Null clears it.", "operationId": "putApiLogisticsStopsByIdCharge", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveryCharge": { "type": "number" } } }, "example": { "deliveryCharge": 350.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsCostsResponseRunsItem" }, "examples": { "default": { "$ref": "#/components/examples/GetApiLogisticsTripsByIdCostResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/drivers/{id}/cost-rate": { "put": { "tags": [ "Logistics & fleet" ], "summary": "What an hour of this driver costs, for a run's cost. Null clears it.", "operationId": "putApiLogisticsDriversByIdCostRate", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLogisticsDriversByIdCostRateRequest" }, "example": { "costPerHour": 85.0 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLogisticsDriversByIdCostRateRequest" }, "example": { "costPerHour": 10005.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/standing-runs": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The company's standing runs: name, vehicle, driver, cadence (weekly, fortnightly, monthly), ordered stops with contact, window and instructions, and the next days each raises a trip on.", "operationId": "getApiLogisticsStandingRuns", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLogisticsStandingRunsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "cadence": "text", "cadenceLabel": "Karoo Fresh Holdings Ltd", "startsOn": "2026-09-01", "endsOn": "2026-09-01", "active": true, "notes": "Budget deferred to the next financial year.", "stops": [ { "stopType": "standard", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "contactPhone": "+27 82 555 0143", "address": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "instructions": "Budget deferred to the next financial year." } ], "nextRuns": [ "text" ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Logistics & fleet" ], "summary": "Create a standing run. Its trips are raised on demand when a planner opens a day on the dispatch board — once per run per day, and never for a day already gone. clientId makes a retry land once.", "operationId": "postApiLogisticsStandingRuns", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsStandingRunsRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsStandingRunsRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsStandingRunsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsStandingRunsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/standing-runs/{id}": { "put": { "tags": [ "Logistics & fleet" ], "summary": "Change a standing run; its stops are replaced as a block. Trips already raised keep what they were raised with.", "operationId": "putApiLogisticsStandingRunsById", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsStandingRunsRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsStandingRunsRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsStandingRunsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsStandingRunsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Logistics & fleet" ], "summary": "Stop a standing run. The trips it already raised stay.", "operationId": "deleteApiLogisticsStandingRunsById", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/stops/{id}/customer": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The stop's customer: the tracking and proof-of-delivery links to hand them (relative paths, valid 90 days), every update they were sent or that is waiting, their rating, and whether they asked not to be told.", "operationId": "getApiLogisticsStopsByIdCustomer", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdCustomerResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiLogisticsStopsByIdCustomerResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/stops/{id}/customer/revoke": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Retire every link this stop's customer holds — tracking, proof and rating at once — and answer with the new ones.", "operationId": "postApiLogisticsStopsByIdCustomerRevoke", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdCustomerResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiLogisticsStopsByIdCustomerResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/contacts/{id}/delivery-updates": { "put": { "tags": [ "Logistics & fleet" ], "summary": "Stop (optedOut true) or resume delivery updates to one contact, on every channel, from now on.", "operationId": "putApiLogisticsContactsByIdDeliveryUpdates", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "optedOut": { "type": "boolean" } } }, "example": { "optedOut": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "optedOut": { "type": "boolean" } } }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "optedOut": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/documents/{id}/deliveries": { "get": { "tags": [ "Logistics & fleet" ], "summary": "How a document went out: one row per stop that carried it, with the line Invoicing shows — \"Delivered in full — signed by …\", and \"signed\" only when a signature was captured. Needs invoices:view.", "operationId": "getApiLogisticsDocumentsByIdDeliveries", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "stopId": { "type": "string" }, "tripNumber": { "type": "string" }, "tripDate": { "type": "string", "format": "date" }, "status": { "type": "string" }, "line": { "type": "string" }, "proofId": { "type": "string" }, "receivedByName": { "type": "string" }, "capturedAt": { "type": "string" } } } }, "example": [ { "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "tripDate": "2026-09-01", "status": "sent", "line": "text", "proofId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "receivedByName": "Karoo Fresh Holdings Ltd", "capturedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/board": { "get": { "tags": [ "Logistics & fleet" ], "summary": "Every vehicle with its state, its current trip and how long since its phone last reported. The screen a fleet controller leaves open. lastPosition (where the vehicle is) is filled only for a tenant holding the Live driver & truck tracking add-on; lastSeenMinutes is filled for every Logistics tenant.", "operationId": "getApiLogisticsBoard", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "vehicleId": { "type": "string" }, "registration": { "type": "string" }, "fleetNumber": { "type": "string" }, "vehicleType": { "type": "string" }, "state": { "type": "string" }, "driverId": { "type": "string" }, "driverName": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "tripStatus": { "type": "string" }, "routeName": { "type": "string" }, "stopsDone": { "type": "integer" }, "stopsTotal": { "type": "integer" }, "lastPosition": { "$ref": "#/components/schemas/GetApiLogisticsBoardResponseItemLastPosition" }, "lastSeenMinutes": { "type": "integer" }, "complianceWarning": { "type": "string" } } } }, "example": [ { "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registration": "text", "fleetNumber": "INV-0001", "vehicleType": "standard", "state": "sent", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "tripStatus": "sent", "routeName": "Karoo Fresh Holdings Ltd", "stopsDone": 1, "stopsTotal": 42, "lastPosition": { "latitude": 1.0, "longitude": 1.0, "accuracyM": 1.0, "speedKph": 1.0, "headingDeg": 1.0, "recordedAt": "2026-09-01T09:15:00Z", "receivedAt": "2026-09-01T09:15:00Z", "batteryPercent": 15, "source": "referral", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ageMinutes": 1 }, "lastSeenMinutes": 1, "complianceWarning": "text" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/summary": { "get": { "tags": [ "Logistics & fleet" ], "summary": "Today's counts, plus what expires in 30 days — the licence disc, the certificate of fitness, the operator card, the driver's licence and the PrDP.", "operationId": "getApiLogisticsSummary", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "vehiclesActive": { "type": "integer" }, "vehiclesOnTrip": { "type": "integer" }, "vehiclesInMaintenance": { "type": "integer" }, "driversActive": { "type": "integer" }, "tripsToday": { "type": "integer" }, "tripsInProgress": { "type": "integer" }, "stopsToday": { "type": "integer" }, "stopsDeliveredToday": { "type": "integer" }, "stopsFailedToday": { "type": "integer" }, "stopsOutstandingToday": { "type": "integer" }, "unassignedDocuments": { "type": "integer" }, "podCapturePercent": { "type": "number" }, "podEvidencePercent": { "type": "number" }, "complianceAlerts": { "type": "integer" }, "currency": { "type": "string" } } }, "example": { "vehiclesActive": 1, "vehiclesOnTrip": 1, "vehiclesInMaintenance": 1, "driversActive": 1, "tripsToday": 1, "tripsInProgress": 1, "stopsToday": 1, "stopsDeliveredToday": 1, "stopsFailedToday": 1, "stopsOutstandingToday": 1, "unassignedDocuments": 1, "podCapturePercent": 15.0, "podEvidencePercent": 15.0, "complianceAlerts": 1, "currency": "ZAR" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/performance": { "get": { "tags": [ "Logistics & fleet" ], "summary": "On-time delivery, failure reasons, distance and cost per trip.", "operationId": "getApiLogisticsPerformance", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-31" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "fromDate": { "type": "string", "format": "date" }, "toDate": { "type": "string", "format": "date" }, "stopsAttempted": { "type": "integer" }, "delivered": { "type": "integer" }, "partial": { "type": "integer" }, "failed": { "type": "integer" }, "successPercent": { "type": "number" }, "onTimePercent": { "type": "number" }, "podCapturePercent": { "type": "number" }, "strongProofs": { "type": "integer" }, "adequateProofs": { "type": "integer" }, "weakProofs": { "type": "integer" }, "failureReasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "category": { "type": "string" }, "count": { "type": "integer" }, "chargeable": { "type": "boolean" } } } }, "byDriver": { "type": "array", "items": { "type": "object", "properties": { "driverId": { "type": "string" }, "driverName": { "type": "string" }, "trips": { "type": "integer" }, "stopsAttempted": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "podCapturePercent": { "type": "number" } } } }, "byVehicle": { "type": "array", "items": { "type": "object", "properties": { "vehicleId": { "type": "string" }, "registration": { "type": "string" }, "trips": { "type": "integer" }, "distanceKm": { "type": "number" }, "stopsDelivered": { "type": "integer" }, "fuelLitres": { "type": "number" }, "fuelCost": { "type": "number" }, "litresPer100Km": { "type": "number" }, "costPerDrop": { "type": "number" }, "currency": { "type": "string" } } } } } }, "example": { "fromDate": "2026-09-01", "toDate": "2026-09-01", "stopsAttempted": 1, "delivered": 1, "partial": 1, "failed": 0, "successPercent": 15.0, "onTimePercent": 15.0, "podCapturePercent": 15.0, "strongProofs": 1, "adequateProofs": 1, "weakProofs": 1, "failureReasons": [ { "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "category": "Office supplies", "count": 3, "chargeable": false } ], "byDriver": [ { "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "trips": 1, "stopsAttempted": 1, "delivered": 1, "failed": 0, "podCapturePercent": 15.0 } ], "byVehicle": [ { "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registration": "text", "trips": 1, "distanceKm": 1.0, "stopsDelivered": 1, "fuelLitres": 1.0, "fuelCost": 10005.0, "litresPer100Km": 1.0, "costPerDrop": 10005.0, "currency": "ZAR" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/unassigned": { "get": { "tags": [ "Logistics & fleet" ], "summary": "Documents ready to deliver that no trip has picked up.", "operationId": "getApiLogisticsUnassigned", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "example": "returns" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsUnassignedResponseItem" } }, "example": [ { "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "documentType": "invoice", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "issueDate": "2026-09-01", "deliveryDate": "2026-09-01", "address": "12 Long Street, Cape Town, 8001", "city": "Cape Town", "postalCode": "CT-001", "lineCount": 3, "totalQty": 3.0, "total": 10005.0, "currency": "ZAR" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/vehicles": { "get": { "tags": [ "Logistics & fleet" ], "summary": "Vehicles with their SA compliance dates as columns rather than a generic documents table.", "operationId": "getApiLogisticsVehicles", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "includeRetired", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" }, { "name": "search", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLogisticsVehiclesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registration": "text", "fleetNumber": "INV-0001", "make": "text", "model": "text", "year": 2026, "vehicleType": "standard", "payloadKg": 1.0, "volumeM3": 1.0, "palletCapacity": 1, "odometerKm": 1.0, "fuelType": "standard", "tankLitres": 1.0, "licenceDiscExpiry": "2026-09-30", "roadworthyExpiry": "2026-09-30", "operatorCardExpiry": "2026-09-30", "status": "sent", "homeLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "homeLocationName": "Karoo Fresh Holdings Ltd", "fixedAssetId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "telematicsExternalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "soonestComplianceExpiryDays": 30, "soonestComplianceExpiryKind": "standard", "onTrip": false, "currentTripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "currentTripNumber": "INV-0001", "lastPosition": { "latitude": 1.0, "longitude": 1.0, "accuracyM": 1.0, "speedKph": 1.0, "headingDeg": 1.0, "recordedAt": "2026-09-01T09:15:00Z", "receivedAt": "2026-09-01T09:15:00Z", "batteryPercent": 15, "source": "referral", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ageMinutes": 1 } } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Logistics & fleet" ], "summary": "Add a vehicle. The operator card applies to goods vehicles over 3 500kg under the NRTA.", "operationId": "postApiLogisticsVehicles", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsVehiclesRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsVehiclesRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsVehiclesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsVehiclesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/vehicles/{id}": { "get": { "tags": [ "Logistics & fleet" ], "summary": "One vehicle with its trip and position history.", "operationId": "getApiLogisticsVehiclesById", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsVehiclesResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registration": "text", "fleetNumber": "INV-0001", "make": "text", "model": "text", "year": 2026, "vehicleType": "standard", "payloadKg": 1.0, "volumeM3": 1.0, "palletCapacity": 1, "odometerKm": 1.0, "fuelType": "standard", "tankLitres": 1.0, "licenceDiscExpiry": "2026-09-30", "roadworthyExpiry": "2026-09-30", "operatorCardExpiry": "2026-09-30", "status": "sent", "homeLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "homeLocationName": "Karoo Fresh Holdings Ltd", "fixedAssetId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "telematicsExternalId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "soonestComplianceExpiryDays": 30, "soonestComplianceExpiryKind": "standard", "onTrip": false, "currentTripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "currentTripNumber": "INV-0001", "lastPosition": { "latitude": 1.0, "longitude": 1.0, "accuracyM": 1.0, "speedKph": 1.0, "headingDeg": 1.0, "recordedAt": "2026-09-01T09:15:00Z", "receivedAt": "2026-09-01T09:15:00Z", "batteryPercent": 15, "source": "referral", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ageMinutes": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Logistics & fleet" ], "summary": "Update a vehicle.", "operationId": "putApiLogisticsVehiclesById", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsVehiclesRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsVehiclesRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsVehiclesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsVehiclesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Logistics & fleet" ], "summary": "Retire a vehicle.", "operationId": "deleteApiLogisticsVehiclesById", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/drivers": { "get": { "tags": [ "Logistics & fleet" ], "summary": "Drivers with their licence code and PrDP category.", "operationId": "getApiLogisticsDrivers", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "includeInactive", "in": "query", "required": false, "description": "Include rows that have been deactivated. Deactivated is not deleted: it means \"stop offering this on new documents\".", "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLogisticsDriversResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fullName": "Karoo Fresh Holdings Ltd", "phone": "+27 82 555 0143", "email": "accounts@karoofresh.example", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "licenceNumber": "INV-0001", "licenceCode": "CT-001", "licenceExpiry": "2026-09-30", "prdpNumber": "INV-0001", "prdpCategories": "text", "prdpExpiry": "2026-09-30", "status": "sent", "defaultVehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "defaultVehicleRegistration": "text", "notes": "Budget deferred to the next financial year.", "soonestDocumentExpiryDays": 30, "soonestDocumentExpiryKind": "standard", "appAccessIssued": false, "appAccessRevokedAt": "2026-09-01T09:15:00Z", "appLastSeenAt": "2026-09-01T09:15:00Z", "openTrips": 1 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Logistics & fleet" ], "summary": "Add a driver. A driver is NOT a user account — the product deliberately does not meter seats, and a seat per driver would break that.", "operationId": "postApiLogisticsDrivers", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsDriversRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsDriversRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsDriversResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsDriversResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/drivers/{id}": { "put": { "tags": [ "Logistics & fleet" ], "summary": "Update a driver.", "operationId": "putApiLogisticsDriversById", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsDriversRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsDriversRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsDriversResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsDriversResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Logistics & fleet" ], "summary": "Retire a driver.", "operationId": "deleteApiLogisticsDriversById", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/drivers/{id}/app-token": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Mint a driver-app credential. Returned ONCE and never retrievable; issuing a new one retires whatever that driver is holding, by bumping drivers.portal_token_version. Add ?days= to shorten the 90-day default.", "operationId": "postApiLogisticsDriversByIdAppToken", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "required": false, "description": "How many days forward or back the window covers.", "schema": { "type": "integer" }, "example": "30" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "driverId": { "type": "string" }, "expiresAt": { "type": "string" } } }, "example": { "token": "", "driverId": "87ba03ee-c9f4-5884-b84e-cdd9ff79c69d", "expiresAt": "2026-11-20T00:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/drivers/{id}/app-token/revoke": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Retire the driver's token now. A JWT is valid until it expires by construction; nothing else can retire one already on a phone.", "operationId": "postApiLogisticsDriversByIdAppTokenRevoke", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsDriversResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fullName": "Karoo Fresh Holdings Ltd", "phone": "+27 82 555 0143", "email": "accounts@karoofresh.example", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "licenceNumber": "INV-0001", "licenceCode": "CT-001", "licenceExpiry": "2026-09-30", "prdpNumber": "INV-0001", "prdpCategories": "text", "prdpExpiry": "2026-09-30", "status": "sent", "defaultVehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "defaultVehicleRegistration": "text", "notes": "Budget deferred to the next financial year.", "soonestDocumentExpiryDays": 30, "soonestDocumentExpiryKind": "standard", "appAccessIssued": false, "appAccessRevokedAt": "2026-09-01T09:15:00Z", "appLastSeenAt": "2026-09-01T09:15:00Z", "openTrips": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips": { "get": { "tags": [ "Logistics & fleet" ], "summary": "Trips with their stops and state.", "operationId": "getApiLogisticsTrips", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "A 1-based page number, on the endpoints that page that way rather than by offset.", "schema": { "type": "integer" }, "example": "1" }, { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "planned" }, { "name": "driverId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "vehicleId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" }, { "name": "search", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" }, { "name": "withStops", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tripNumber": { "type": "string" }, "tripDate": { "type": "string", "format": "date" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "vehicleFleetNumber": { "type": "string" }, "driverId": { "type": "string" }, "driverName": { "type": "string" }, "coDriverId": { "type": "string" }, "coDriverName": { "type": "string" }, "status": { "type": "string" }, "routeName": { "type": "string" }, "plannedDeparture": { "type": "string" }, "actualDeparture": { "type": "string" }, "plannedReturn": { "type": "string" }, "actualReturn": { "type": "string" }, "startOdometerKm": { "type": "number" }, "endOdometerKm": { "type": "number" }, "odometerDistanceKm": { "type": "number" }, "trackedDistanceKm": { "type": "number" }, "fuelLitres": { "type": "number" }, "fuelCost": { "type": "number" }, "fuelExpenseId": { "type": "string" }, "notes": { "type": "string" }, "cancelledReason": { "type": "string" }, "dispatchedAt": { "type": "string" }, "completedAt": { "type": "string" }, "stopCount": { "type": "integer" }, "stopsCompleted": { "type": "integer" }, "stopsFailed": { "type": "integer" }, "stopsWithProof": { "type": "integer" }, "litresPer100Km": { "type": "number" }, "costPerDrop": { "type": "number" }, "currency": { "type": "string" }, "stops": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "sequence": { "type": "integer" }, "stopType": { "type": "string" }, "contactId": { "type": "string" }, "contactDisplayName": { "type": "string" }, "documentId": { "type": "string" }, "documentNumber": { "type": "string" }, "documentType": { "type": "string" }, "jobCardId": { "type": "string" }, "jobCardNumber": { "type": "string" }, "stockLocationId": { "type": "string" }, "address": { "type": "string" }, "suburb": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "contactName": { "type": "string" }, "contactPhone": { "type": "string" }, "instructions": { "type": "string" }, "windowFrom": { "type": "string", "format": "date" }, "windowTo": { "type": "string", "format": "date" }, "status": { "type": "string" }, "enRouteAt": { "type": "string" }, "arrivedAt": { "type": "string" }, "departedAt": { "type": "string" }, "arrivalLatitude": { "type": "number" }, "arrivalLongitude": { "type": "number" }, "arrivalAccuracyM": { "type": "number" }, "arrivalDistanceM": { "type": "number" }, "exceptionReasonCode": { "type": "string" }, "exceptionReasonLabel": { "type": "string" }, "exceptionNotes": { "type": "string" }, "stockPostedAt": { "type": "string" }, "stockWarnings": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponseLinesItem" } }, "proof": { "type": "object", "properties": { "id": { "type": "string" }, "stopId": { "type": "string" }, "tripId": { "type": "string" }, "outcome": { "type": "string" }, "receivedByName": { "type": "string" }, "receivedByRole": { "type": "string" }, "signatureAttachmentId": { "type": "string" }, "notes": { "type": "string" }, "capturedLatitude": { "type": "number" }, "capturedLongitude": { "type": "number" }, "capturedAccuracyM": { "type": "number" }, "distanceFromStopM": { "type": "number" }, "capturedAt": { "type": "string" }, "recordedAt": { "type": "string" }, "clockSkewMinutes": { "type": "integer" }, "driverId": { "type": "string" }, "driverName": { "type": "string" }, "deviceId": { "type": "string" }, "exceptionReasonCode": { "type": "string" }, "exceptionReasonLabel": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object" } }, "capturedInOffice": { "type": "boolean" }, "learnableLocation": { "type": "boolean" }, "strength": { "type": "string" }, "evidenceStatement": { "type": "string" }, "weaknesses": { "type": "array", "items": { "type": "object" } } } }, "collectable": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponseCollectable" }, "collection": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponseCollection" } } } }, "load": { "$ref": "#/components/schemas/PostApiLogisticsTripsResponseLoad" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "tripDate": "2026-09-01", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "vehicleFleetNumber": "INV-0001", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "coDriverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "coDriverName": "Karoo Fresh Holdings Ltd", "status": "sent", "routeName": "Karoo Fresh Holdings Ltd", "plannedDeparture": "text", "actualDeparture": "text", "plannedReturn": "text", "actualReturn": "text", "startOdometerKm": 1.0, "endOdometerKm": 1.0, "odometerDistanceKm": 1.0, "trackedDistanceKm": 1.0, "fuelLitres": 1.0, "fuelCost": 10005.0, "fuelExpenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "cancelledReason": "Budget deferred to the next financial year.", "dispatchedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "stopCount": 3, "stopsCompleted": 1, "stopsFailed": 0, "stopsWithProof": 1, "litresPer100Km": 1.0, "costPerDrop": 10005.0, "currency": "ZAR", "stops": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "sequence": 1, "stopType": "delivery", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactDisplayName": "Karoo Fresh Holdings Ltd", "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "documentType": "invoice", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobCardNumber": "JC-0001", "stockLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "address": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "latitude": 1.0, "longitude": 1.0, "contactName": "Karoo Fresh Holdings Ltd", "contactPhone": "+27 82 555 0143", "instructions": "Budget deferred to the next financial year.", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "status": "sent", "enRouteAt": "2026-09-01T09:15:00Z", "arrivedAt": "2026-09-01T09:15:00Z", "departedAt": "2026-09-01T09:15:00Z", "arrivalLatitude": 1.0, "arrivalLongitude": 1.0, "arrivalAccuracyM": 1.0, "arrivalDistanceM": 1.0, "exceptionReasonCode": "CT-001", "exceptionReasonLabel": "Karoo Fresh Holdings Ltd", "exceptionNotes": "Budget deferred to the next financial year.", "stockPostedAt": "2026-09-01T09:15:00Z", "stockWarnings": [ "text" ], "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyOrdered": 1.0, "qtyDelivered": 1.0, "qtyReturned": 1.0, "uom": "each", "batchNumber": "INV-0001", "stockMovementId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "shortfall": 1.0, "qtyLoaded": 1.0, "loadCheckedAt": "2026-09-01T09:15:00Z", "service": false } ], "proof": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "outcome": "delivered", "receivedByName": "Karoo Fresh Holdings Ltd", "receivedByRole": "Accountant", "signatureAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "capturedLatitude": 1.0, "capturedLongitude": 1.0, "capturedAccuracyM": 1.0, "distanceFromStopM": 1.0, "capturedAt": "2026-09-01T09:15:00Z", "recordedAt": "2026-09-01T09:15:00Z", "clockSkewMinutes": 1, "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "deviceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "exceptionReasonCode": "CT-001", "exceptionReasonLabel": "Karoo Fresh Holdings Ltd", "photos": [], "capturedInOffice": false, "learnableLocation": false, "strength": "STRONG", "evidenceStatement": "text", "weaknesses": [] }, "collectable": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "amountDue": 10005.0, "foreignCurrency": "ZAR" }, "collection": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "paymentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 10005.0, "method": "cash", "reference": "INV-0001", "collectedAt": "2026-09-01T09:15:00Z", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "bankedAt": "2026-09-01T09:15:00Z", "bankingId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } ], "load": { "weightKg": 1.0, "volumeM3": 1.0, "pallets": 1, "payloadKg": 1.0, "vehicleVolumeM3": 1.0, "vehiclePallets": 1, "linesWithoutWeight": 1, "warnings": [] } } ], "total": 42, "page": 1, "limit": 20, "totalPages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Logistics & fleet" ], "summary": "Plan a trip — one vehicle, one driver, one run. Numbered from the shared document_sequences series under doc_type 'trip'.", "operationId": "postApiLogisticsTrips", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsTripsRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsTripsRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsTripsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsTripsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}": { "get": { "tags": [ "Logistics & fleet" ], "summary": "One trip with its ordered stops.", "operationId": "getApiLogisticsTripsById", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tripNumber": { "type": "string" }, "tripDate": { "type": "string", "format": "date" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "vehicleFleetNumber": { "type": "string" }, "driverId": { "type": "string" }, "driverName": { "type": "string" }, "coDriverId": { "type": "string" }, "coDriverName": { "type": "string" }, "status": { "type": "string" }, "routeName": { "type": "string" }, "plannedDeparture": { "type": "string" }, "actualDeparture": { "type": "string" }, "plannedReturn": { "type": "string" }, "actualReturn": { "type": "string" }, "startOdometerKm": { "type": "number" }, "endOdometerKm": { "type": "number" }, "odometerDistanceKm": { "type": "number" }, "trackedDistanceKm": { "type": "number" }, "fuelLitres": { "type": "number" }, "fuelCost": { "type": "number" }, "fuelExpenseId": { "type": "string" }, "notes": { "type": "string" }, "cancelledReason": { "type": "string" }, "dispatchedAt": { "type": "string" }, "completedAt": { "type": "string" }, "stopCount": { "type": "integer" }, "stopsCompleted": { "type": "integer" }, "stopsFailed": { "type": "integer" }, "stopsWithProof": { "type": "integer" }, "litresPer100Km": { "type": "number" }, "costPerDrop": { "type": "number" }, "currency": { "type": "string" }, "stops": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "sequence": { "type": "integer" }, "stopType": { "type": "string" }, "contactId": { "type": "string" }, "contactDisplayName": { "type": "string" }, "documentId": { "type": "string" }, "documentNumber": { "type": "string" }, "documentType": { "type": "string" }, "jobCardId": { "type": "string" }, "jobCardNumber": { "type": "string" }, "stockLocationId": { "type": "string" }, "address": { "type": "string" }, "suburb": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "contactName": { "type": "string" }, "contactPhone": { "type": "string" }, "instructions": { "type": "string" }, "windowFrom": { "type": "string", "format": "date" }, "windowTo": { "type": "string", "format": "date" }, "status": { "type": "string" }, "enRouteAt": { "type": "string" }, "arrivedAt": { "type": "string" }, "departedAt": { "type": "string" }, "arrivalLatitude": { "type": "number" }, "arrivalLongitude": { "type": "number" }, "arrivalAccuracyM": { "type": "number" }, "arrivalDistanceM": { "type": "number" }, "exceptionReasonCode": { "type": "string" }, "exceptionReasonLabel": { "type": "string" }, "exceptionNotes": { "type": "string" }, "stockPostedAt": { "type": "string" }, "stockWarnings": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceLineId": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "qtyOrdered": { "type": "number" }, "qtyDelivered": { "type": "number" }, "qtyReturned": { "type": "number" }, "uom": { "type": "string" }, "batchNumber": { "type": "string" }, "stockMovementId": { "type": "string" }, "notes": { "type": "string" }, "shortfall": { "type": "number" } } } }, "proof": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdProofResponse" } } } } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "tripDate": "2026-09-01", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "vehicleFleetNumber": "INV-0001", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "coDriverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "coDriverName": "Karoo Fresh Holdings Ltd", "status": "sent", "routeName": "Karoo Fresh Holdings Ltd", "plannedDeparture": "text", "actualDeparture": "text", "plannedReturn": "text", "actualReturn": "text", "startOdometerKm": 1.0, "endOdometerKm": 1.0, "odometerDistanceKm": 1.0, "trackedDistanceKm": 1.0, "fuelLitres": 1.0, "fuelCost": 10005.0, "fuelExpenseId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "cancelledReason": "Budget deferred to the next financial year.", "dispatchedAt": "2026-09-01T09:15:00Z", "completedAt": "2026-09-01T09:15:00Z", "stopCount": 3, "stopsCompleted": 1, "stopsFailed": 0, "stopsWithProof": 1, "litresPer100Km": 1.0, "costPerDrop": 10005.0, "currency": "ZAR", "stops": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "sequence": 1, "stopType": "standard", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactDisplayName": "Karoo Fresh Holdings Ltd", "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "documentType": "invoice", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobCardNumber": "JC-0001", "stockLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "address": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "latitude": 1.0, "longitude": 1.0, "contactName": "Karoo Fresh Holdings Ltd", "contactPhone": "+27 82 555 0143", "instructions": "Budget deferred to the next financial year.", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "status": "sent", "enRouteAt": "2026-09-01T09:15:00Z", "arrivedAt": "2026-09-01T09:15:00Z", "departedAt": "2026-09-01T09:15:00Z", "arrivalLatitude": 1.0, "arrivalLongitude": 1.0, "arrivalAccuracyM": 1.0, "arrivalDistanceM": 1.0, "exceptionReasonCode": "CT-001", "exceptionReasonLabel": "Karoo Fresh Holdings Ltd", "exceptionNotes": "Budget deferred to the next financial year.", "stockPostedAt": "2026-09-01T09:15:00Z", "stockWarnings": [ "text" ], "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyOrdered": 1.0, "qtyDelivered": 1.0, "qtyReturned": 1.0, "uom": "each", "batchNumber": "INV-0001", "stockMovementId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "shortfall": 1.0 } ], "proof": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "outcome": "text", "receivedByName": "Karoo Fresh Holdings Ltd", "receivedByRole": "Accountant", "signatureAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "capturedLatitude": 1.0, "capturedLongitude": 1.0, "capturedAccuracyM": 1.0, "distanceFromStopM": 1.0, "capturedAt": "2026-09-01T09:15:00Z", "recordedAt": "2026-09-01T09:15:00Z", "clockSkewMinutes": 1, "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "deviceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "exceptionReasonCode": "CT-001", "exceptionReasonLabel": "Karoo Fresh Holdings Ltd", "photos": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "caption": "Serial plate before fitting", "sequence": 1 } ], "strength": "STRONG", "evidenceStatement": "text", "weaknesses": [ "text" ] } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Logistics & fleet" ], "summary": "Change a trip's vehicle, driver or date.", "operationId": "putApiLogisticsTripsById", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsTripsRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsTripsRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsTripsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsTripsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Logistics & fleet" ], "summary": "Delete a planned trip.", "operationId": "deleteApiLogisticsTripsById", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}/status": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Move a trip through planned, loading, dispatched, in_progress, completed. Departure and completion both require an odometer reading.", "operationId": "postApiLogisticsTripsByIdStatus", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "odometerKm": { "type": "number" }, "fuelLitres": { "type": "number" }, "fuelCost": { "type": "number" }, "reason": { "type": "string" } } }, "example": { "status": "sent", "odometerKm": 1.0, "fuelLitres": 1.0, "fuelCost": 10005.0, "reason": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsTripsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsTripsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}/stops": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Add a stop that is not a document — a collection, a return, a site visit or the depot leg.", "operationId": "postApiLogisticsTripsByIdStops", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLogisticsStopsByIdRequest" }, "examples": { "default": { "$ref": "#/components/examples/PutApiLogisticsStopsByIdRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiLogisticsStopsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/loads/{documentId}/transfer": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Raise the stock transfer a load's branch is short of — from the supply rule's source when it holds the shortfall, else the nearest branch that does. The load waits on it; a second press raises none.", "operationId": "postApiLogisticsLoadsByDocumentIdTransfer", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "raised": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "raised": 1, "message": "Transfer raised from Johannesburg — the load waits for it." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}/stops/from-document": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Add a stop built from a delivery note, invoice, pro-forma or purchase order — all three live in invoices, so one column covers them. Carries the customer, the address and every LINE, which is what lets a short delivery raise a credit note later.", "operationId": "postApiLogisticsTripsByIdStopsFromDocument", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string" }, "windowFrom": { "type": "string", "format": "date" }, "windowTo": { "type": "string", "format": "date" }, "instructions": { "type": "string" } } }, "example": { "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "instructions": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiLogisticsStopsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}/suggested-sequence": { "get": { "tags": [ "Logistics & fleet" ], "summary": "A shorter order for the run, as advice. Read-only: it reorders nothing. Distances are straight-line between the stops' own coordinates rather than a road route, so the saving is reported and the planner decides; post the ids to /resequence to accept it. Refuses with a reason when the trip has already started, has fewer than three stops, or has fewer than three stops carrying coordinates.", "operationId": "getApiLogisticsTripsByIdSuggestedSequence", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "applicable": { "type": "boolean" }, "stopIds": { "type": "array", "items": { "type": "string" } }, "currentDistanceKm": { "type": "number" }, "suggestedDistanceKm": { "type": "number" }, "savedKm": { "type": "number" }, "worthApplying": { "type": "boolean" }, "note": { "type": "string" }, "reason": { "type": "string" } } }, "example": { "applicable": true, "stopIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "currentDistanceKm": 1.0, "suggestedDistanceKm": 1.0, "savedKm": 1.0, "worthApplying": false, "note": "Budget deferred to the next financial year.", "reason": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}/resequence": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Reorder the stops.", "operationId": "postApiLogisticsTripsByIdResequence", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stopIds": { "type": "array", "items": { "type": "string" } } } }, "example": { "stopIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsTripsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsTripsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/tracking/trips/{id}": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The trip replay — every stored position in order. Part of the Live driver & truck tracking add-on: a Logistics tenant without it is refused 403 MODULE_NOT_LICENSED.", "operationId": "getApiLogisticsTrackingTripsById", "description": "Requires the `driver-tracking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "driver-tracking:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tripId": { "type": "string" }, "tripNumber": { "type": "string" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsBoardResponseItemLastPosition" } }, "trackedDistanceKm": { "type": "number" }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponse" } } } }, "example": { "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "points": [ { "latitude": 1.0, "longitude": 1.0, "accuracyM": 1.0, "speedKph": 1.0, "headingDeg": 1.0, "recordedAt": "2026-09-01T09:15:00Z", "receivedAt": "2026-09-01T09:15:00Z", "batteryPercent": 15, "source": "driver_app", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ageMinutes": 1 } ], "trackedDistanceKm": 1.0, "stops": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "sequence": 1, "stopType": "delivery", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactDisplayName": "Karoo Fresh Holdings Ltd", "documentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "documentNumber": "INV-0001", "documentType": "invoice", "jobCardId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "jobCardNumber": "JC-0001", "stockLocationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "address": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "latitude": 1.0, "longitude": 1.0, "contactName": "Karoo Fresh Holdings Ltd", "contactPhone": "+27 82 555 0143", "instructions": "Budget deferred to the next financial year.", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "status": "sent", "enRouteAt": "2026-09-01T09:15:00Z", "arrivedAt": "2026-09-01T09:15:00Z", "departedAt": "2026-09-01T09:15:00Z", "arrivalLatitude": 1.0, "arrivalLongitude": 1.0, "arrivalAccuracyM": 1.0, "arrivalDistanceM": 1.0, "exceptionReasonCode": "CT-001", "exceptionReasonLabel": "Karoo Fresh Holdings Ltd", "exceptionNotes": "Budget deferred to the next financial year.", "stockPostedAt": "2026-09-01T09:15:00Z", "stockWarnings": [ "text" ], "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyOrdered": 1.0, "qtyDelivered": 1.0, "qtyReturned": 1.0, "uom": "each", "batchNumber": "INV-0001", "stockMovementId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "shortfall": 1.0, "qtyLoaded": 1.0, "loadCheckedAt": "2026-09-01T09:15:00Z", "service": false } ], "proof": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "outcome": "delivered", "receivedByName": "Karoo Fresh Holdings Ltd", "receivedByRole": "Accountant", "signatureAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "capturedLatitude": 1.0, "capturedLongitude": 1.0, "capturedAccuracyM": 1.0, "distanceFromStopM": 1.0, "capturedAt": "2026-09-01T09:15:00Z", "recordedAt": "2026-09-01T09:15:00Z", "clockSkewMinutes": 1, "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "deviceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "exceptionReasonCode": "CT-001", "exceptionReasonLabel": "Karoo Fresh Holdings Ltd", "photos": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "caption": "Serial plate before fitting", "sequence": 1 } ], "capturedInOffice": false, "learnableLocation": false, "strength": "STRONG", "evidenceStatement": "text", "weaknesses": [ "text" ] }, "collectable": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "amountDue": 10005.0, "foreignCurrency": "ZAR" }, "collection": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "paymentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 10005.0, "method": "cash", "reference": "INV-0001", "collectedAt": "2026-09-01T09:15:00Z", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "bankedAt": "2026-09-01T09:15:00Z", "bankingId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/stops/{id}": { "get": { "tags": [ "Logistics & fleet" ], "summary": "One stop with its lines and window.", "operationId": "getApiLogisticsStopsById", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiLogisticsStopsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Logistics & fleet" ], "summary": "Change a stop.", "operationId": "putApiLogisticsStopsById", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLogisticsStopsByIdRequest" }, "examples": { "default": { "$ref": "#/components/examples/PutApiLogisticsStopsByIdRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiLogisticsStopsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Logistics & fleet" ], "summary": "Remove a stop.", "operationId": "deleteApiLogisticsStopsById", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiCrmLeadsByIdResponse" }, "example": { "status": "deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/stops/{id}/proof": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The proof recorded at a stop, with its grade.", "operationId": "getApiLogisticsStopsByIdProof", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdProofResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "outcome": "text", "receivedByName": "Karoo Fresh Holdings Ltd", "receivedByRole": "Accountant", "signatureAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "capturedLatitude": 1.0, "capturedLongitude": 1.0, "capturedAccuracyM": 1.0, "distanceFromStopM": 1.0, "capturedAt": "2026-09-01T09:15:00Z", "recordedAt": "2026-09-01T09:15:00Z", "clockSkewMinutes": 1, "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "deviceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "exceptionReasonCode": "CT-001", "exceptionReasonLabel": "Karoo Fresh Holdings Ltd", "photos": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "caption": "Serial plate before fitting", "sequence": 1 } ], "strength": "STRONG", "evidenceStatement": "text", "weaknesses": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Logistics & fleet" ], "summary": "Record the outcome — who received it, the quantities that actually changed hands, and a drawn signature. Where the per-line quantities disagree with the tapped outcome, THE LINES WIN, and a blank line counts as not delivered. distanceFromStopM is computed server-side from two coordinate pairs and never accepted from a client.", "operationId": "postApiLogisticsStopsByIdProof", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1StopsByIdProofRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostDriverApiV1StopsByIdProofRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "proof": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponseProof" }, "stopStatus": { "type": "string" }, "duplicate": { "type": "boolean" }, "stockWarnings": { "type": "array", "items": { "type": "string" } }, "stockSkippedReason": { "type": "string" } } }, "example": { "proof": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "outcome": "delivered", "receivedByName": "Karoo Fresh Holdings Ltd", "receivedByRole": "Accountant", "signatureAttachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Budget deferred to the next financial year.", "capturedLatitude": 1.0, "capturedLongitude": 1.0, "capturedAccuracyM": 1.0, "distanceFromStopM": 1.0, "capturedAt": "2026-09-01T09:15:00Z", "recordedAt": "2026-09-01T09:15:00Z", "clockSkewMinutes": 1, "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "deviceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "exceptionReasonCode": "CT-001", "exceptionReasonLabel": "Karoo Fresh Holdings Ltd", "photos": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "attachmentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "caption": "Serial plate before fitting", "sequence": 1 } ], "capturedInOffice": false, "learnableLocation": false, "strength": "STRONG", "evidenceStatement": "text", "weaknesses": [ "text" ] }, "stopStatus": "sent", "duplicate": false, "stockWarnings": [ "text" ], "stockSkippedReason": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/proofs/{id}/photos": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Attach a photograph to a proof. At most six; the server recompresses.", "operationId": "postApiLogisticsProofsByIdPhotos", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "caption", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Serial%20plate%20before%20fitting" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpForecastsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/proofs/{id}/html": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The proof as a document — who signed, where they stood, when, the quantities, and an honest statement of what the evidence is worth. Do not improve a weak grade's wording.", "operationId": "getApiLogisticsProofsByIdHtml", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/exception-reasons": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The failure reason list. The seeded set carries LOAD SHEDDING — the most common reason a South African delivery is turned away, and one no other product's standard list has.", "operationId": "getApiLogisticsExceptionReasons", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "includeInactive", "in": "query", "required": false, "description": "Include rows that have been deactivated. Deactivated is not deleted: it means \"stop offering this on new documents\".", "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLogisticsExceptionReasonsResponse" } }, "examples": { "default": { "$ref": "#/components/examples/GetDriverApiV1ExceptionReasonsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Logistics & fleet" ], "summary": "Add a reason code.", "operationId": "postApiLogisticsExceptionReasons", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsExceptionReasonsRequest" }, "example": { "code": "site_closed", "label": "Site closed on arrival", "category": "customer", "isFailure": true, "isChargeable": false, "sortOrder": 1, "active": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsExceptionReasonsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsExceptionReasonsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/exception-reasons/{id}": { "put": { "tags": [ "Logistics & fleet" ], "summary": "Relabel or retire a reason code.", "operationId": "putApiLogisticsExceptionReasonsById", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsExceptionReasonsRequest" }, "example": { "code": "CT-001", "label": "Karoo Fresh Holdings Ltd", "category": "customer", "isFailure": true, "isChargeable": false, "sortOrder": 1, "active": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsExceptionReasonsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLogisticsExceptionReasonsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/positions": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Post GPS fixes from a third-party tracker. Identify the vehicle by Ledgr's id or by telematicsExternalId, which is the id your own platform already knows it by. A 60s floor is enforced against the previous fix's DEVICE time, future-dated fixes are refused, a batch caps at 500, and what was dropped is reported.", "operationId": "postApiLogisticsPositions", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vehicleId": { "type": "string" }, "telematicsExternalId": { "type": "string" }, "driverId": { "type": "string" }, "source": { "type": "string" }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/PostDriverApiV1PositionsRequestPositionsItem" } } } }, "example": { "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "telematicsExternalId": "TRK-4092", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "source": "telematics", "positions": [ { "latitude": -33.9249, "longitude": 18.4241, "accuracyM": 1.0, "speedKph": 62.0, "headingDeg": 1.0, "altitudeM": 1.0, "recordedAt": "2026-08-25T09:14:00Z", "batteryPercent": 15, "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "integer" }, "rejected": { "type": "integer" }, "reasons": { "type": "array", "items": { "type": "object" } } } }, "example": { "accepted": 1, "rejected": 0, "reasons": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/tracking/fleet-map": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The fleet map's framed backdrop plus the vehicles to draw on it. Part of the Live driver & truck tracking add-on: a Logistics tenant without it is refused 403 MODULE_NOT_LICENSED. Send the pixel size you will render at — the server picks the zoom that frames every reporting vehicle inside exactly that box, and the client places markers with the same Web Mercator projection. Answers available=false with a reason, rather than failing, when no maps key is configured. Pass lat, lon and zoom TOGETHER to draw a view the controller has panned or zoomed to instead of the framed one; all three or none, and a view the projection cannot draw is refused rather than quietly replaced with the framed view.", "operationId": "getApiLogisticsTrackingFleetMap", "description": "Requires the `driver-tracking:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "driver-tracking:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "unavailableReason": { "type": "string" }, "imageUrl": { "type": "string" }, "centreLatitude": { "type": "number" }, "centreLongitude": { "type": "number" }, "zoom": { "type": "integer" }, "widthPx": { "type": "integer" }, "heightPx": { "type": "integer" }, "plotted": { "type": "array", "items": { "type": "object", "properties": { "vehicleId": { "type": "string" }, "registration": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" } } } }, "attribution": { "type": "string" } } }, "example": { "available": false, "unavailableReason": "Budget deferred to the next financial year.", "imageUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "centreLatitude": 1.0, "centreLongitude": 1.0, "zoom": 1, "widthPx": 1, "heightPx": 1, "plotted": [ { "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registration": "text", "latitude": 1.0, "longitude": 1.0 } ], "attribution": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/delivery-slots": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The delivery windows this company lets customers book on their tracking link, like 08:00-12:00.", "operationId": "getApiLogisticsDeliverySlots", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLogisticsDeliverySlotsRequest" }, "example": { "slots": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Logistics & fleet" ], "summary": "Set the delivery windows customers may book. Each is two clock times, the first before the second; at most twelve. An empty list offers none. Needs logistics:edit.", "operationId": "putApiLogisticsDeliverySlots", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLogisticsDeliverySlotsRequest" }, "example": { "slots": [ "08:00-12:00", "12:00-17:00" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiLogisticsDeliverySlotsRequest" }, "example": { "slots": [ "text" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/drivers/{id}/settle": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Settle a contractor driver's period into a draft supplier bill: completed drops, km or hours on their completed trips dated in the period, at their rate, billed as their supplier. 201 with the settlement; 200 with the same bill when this exact period was settled before; 400 for an employee driver (paid through payroll), a driver with no settlement basis, a period overlapping one already settled, a period over 93 days, or nothing to settle. Needs logistics:edit and expenses:create.", "operationId": "postApiLogisticsDriversByIdSettle", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLogisticsDriversByIdSettleRequest" }, "example": { "from": "2026-10-01", "to": "2026-10-31" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "billId": { "type": "string" }, "basis": { "type": "string" }, "quantity": { "type": "number" }, "rate": { "type": "number" }, "amount": { "type": "number" }, "periodFrom": { "type": "string", "format": "date" }, "periodTo": { "type": "string", "format": "date" }, "alreadySettled": { "type": "boolean" } } }, "example": { "billId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "basis": "invoice", "quantity": 3.0, "rate": 15.0, "amount": 10005.0, "periodFrom": "2026-09-01", "periodTo": "2026-09-30", "alreadySettled": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}/messages": { "get": { "tags": [ "Logistics & fleet" ], "summary": "A trip's thread between the office and its driver, in the order the messages were written (not the order they arrived). Reading it marks the driver's messages delivered. Needs logistics:view.", "operationId": "getApiLogisticsTripsByIdMessages", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDriverApiV1TripsByIdMessagesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetDriverApiV1TripsByIdMessagesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Logistics & fleet" ], "summary": "Write to the trip's driver. id is minted by the writer before the first attempt: 201 for a new message, 200 with the stored one on a retry. writtenAt orders the thread; clientSeq orders two written in the same instant. An empty message is refused. Needs logistics:edit.", "operationId": "postApiLogisticsTripsByIdMessages", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1TripsByIdMessagesRequest" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "body": "What is the gate code?", "clientSeq": 1, "writtenAt": "2026-10-12T08:00:00+02:00" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1TripsByIdMessagesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostDriverApiV1TripsByIdMessagesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}/messages/photo": { "post": { "tags": [ "Logistics & fleet" ], "summary": "A photo on the trip's thread. Raw image bytes as the body; the message's id, clientSeq, writtenAt and an optional caption on the query. Refused unless the bytes are an image. Needs logistics:edit.", "operationId": "postApiLogisticsTripsByIdMessagesPhoto", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "clientSeq", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" }, { "name": "writtenAt", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-10-12T08%3A00%3A00%2B02%3A00" }, { "name": "caption", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Gate" } ], "responses": { "201": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/trips/{id}/messages/read": { "post": { "tags": [ "Logistics & fleet" ], "summary": "The office has read the thread: every driver message on it is marked read. Needs logistics:edit — a viewer reading the thread does not tell the driver it was read.", "operationId": "postApiLogisticsTripsByIdMessagesRead", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1TripsByIdMessagesReadResponse" }, "example": { "read": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/returnables": { "get": { "tags": [ "Logistics & fleet" ], "summary": "What each customer holds of each returnable container (crates, pallets, cylinders) — the sum of what drivers counted out less what came back — and its deposit per unit. contactId narrows it to one customer.", "operationId": "getApiLogisticsReturnables", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contactId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "contactId": { "type": "string" }, "contactName": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "balance": { "type": "number" }, "depositPerUnit": { "type": "number" } } } }, "example": [ { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactName": "Karoo Fresh Holdings Ltd", "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "productName": "Karoo Fresh Holdings Ltd", "balance": 10005.0, "depositPerUnit": 1.0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/cash": { "get": { "tags": [ "Logistics & fleet" ], "summary": "Cash collected on delivery and not yet banked, per driver — what 1365 Cash in transit holds. The bank accounts to bank it into come with it for a caller who may bank.", "operationId": "getApiLogisticsCash", "description": "Requires the `logistics:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "drivers": { "type": "array", "items": { "type": "object", "properties": { "driverId": { "type": "string" }, "driverName": { "type": "string" }, "toHandIn": { "type": "number" }, "collections": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiLogisticsStopsByIdResponseCollection" } } } } }, "totalToHandIn": { "type": "number" }, "bankAccounts": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } }, "canBank": { "type": "boolean" } } }, "example": { "drivers": [ { "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "toHandIn": 1.0, "collections": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "paymentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 10005.0, "method": "cash", "reference": "INV-0001", "collectedAt": "2026-09-01T09:15:00Z", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "bankedAt": "2026-09-01T09:15:00Z", "bankingId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } ], "totalToHandIn": 10005.0, "bankAccounts": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd" } ], "canBank": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logistics/cash/bank": { "post": { "tags": [ "Logistics & fleet" ], "summary": "Bank a driver's cash: marks the collections banked and posts DR 1350 Bank / CR 1365 Cash in transit. Needs banking:create. An empty collectionIds banks all of the driver's unbanked cash; send clientReference and a retry lands once.", "operationId": "postApiLogisticsCashBank", "description": "Requires the `logistics:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "logistics:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "driverId": { "type": "string" }, "bankAccountId": { "type": "string" }, "collectionIds": { "type": "array", "items": { "type": "string" } }, "date": { "type": "string", "format": "date" }, "reference": { "type": "string" }, "clientReference": { "type": "string" } } }, "example": { "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "collectionIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "date": "2026-09-01", "reference": "INV-0001", "clientReference": "INV-0001" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "driverId": { "type": "string" }, "bankAccountId": { "type": "string" }, "bankAccountName": { "type": "string" }, "amount": { "type": "number" }, "bankedOn": { "type": "string", "format": "date" }, "reference": { "type": "string" }, "collectionCount": { "type": "integer" }, "duplicate": { "type": "boolean" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "bankAccountName": "Karoo Fresh Holdings Ltd", "amount": 10005.0, "bankedOn": "2026-09-01", "reference": "INV-0001", "collectionCount": 3, "duplicate": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/fuel": { "post": { "tags": [ "Driver app API" ], "summary": "A fill-up at the pump, by the driver: only a vehicle they drive (their own, or the one on a trip they are out on). Posts one zero-rated fuel expense; send clientReference and a retry lands once.", "operationId": "postDriverApiV1Fuel", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1FuelRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostDriverApiV1FuelRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1FuelResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostDriverApiV1FuelResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/trips/{id}/load-check": { "post": { "tags": [ "Driver app API" ], "summary": "What the driver counted on board before leaving, per stop line (null = not established). Never refuses the departure; the office sees a line that left short. Writing the same check twice leaves the same figures.", "operationId": "postDriverApiV1TripsByIdLoadCheck", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "temperatures": { "type": "array", "items": { "$ref": "#/components/schemas/PostDriverApiV1StopsByIdProofRequestTemperaturesItem" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "stopLineId": { "type": "string" }, "qtyLoaded": { "type": "number" } } } } } }, "example": { "temperatures": [ { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "celsius": 4.0 } ], "lines": [ { "stopLineId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "qtyLoaded": 1.0 } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "linesRecorded": { "type": "integer" }, "linesShort": { "type": "integer" } } }, "example": { "linesRecorded": 1, "linesShort": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/session": { "get": { "tags": [ "Driver app API" ], "summary": "Who the token belongs to, what vehicle they usually drive, how often to TAKE a position and how often to SEND the batch, and the SERVER's own clock so the app can measure its skew. Send Authorization: Bearer — not a user JWT. Sample at positionIntervalSeconds and buffer; POST the batch every positionFlushSeconds. Do not send one fix per request: a fix closer than 60s to the last stored one is refused, and a batch is how a phone that has been out of signal catches up.", "operationId": "getDriverApiV1Session", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "driverId": { "type": "string" }, "driverName": { "type": "string" }, "tenantName": { "type": "string" }, "companyName": { "type": "string" }, "phone": { "type": "string" }, "defaultVehicleId": { "type": "string" }, "defaultVehicleRegistration": { "type": "string" }, "openTripCount": { "type": "integer" }, "positionIntervalSeconds": { "type": "integer" }, "positionFlushSeconds": { "type": "integer" }, "serverTime": { "type": "string" }, "tokenExpiresAt": { "type": "string" } } }, "example": { "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "tenantName": "Karoo Fresh Holdings Ltd", "companyName": "Karoo Fresh Holdings Ltd", "phone": "+27 82 555 0143", "defaultVehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "defaultVehicleRegistration": "text", "openTripCount": 3, "positionIntervalSeconds": 1, "positionFlushSeconds": 1, "serverTime": "2026-09-01T09:15:00Z", "tokenExpiresAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/trips": { "get": { "tags": [ "Driver app API" ], "summary": "The trips this driver may act on. Each manifest carries its stops, and each stop its lines, its address and its phone number.", "operationId": "getDriverApiV1Trips", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetDriverApiV1TripsByIdResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "tripDate": "2026-09-01", "status": "sent", "routeName": "Karoo Fresh Holdings Ltd", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "plannedDeparture": "text", "startOdometerKm": 1.0, "notes": "Budget deferred to the next financial year.", "stops": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sequence": 1, "stopType": "standard", "status": "sent", "customerName": "Karoo Fresh Holdings Ltd", "documentNumber": "INV-0001", "address": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "latitude": 1.0, "longitude": 1.0, "contactName": "Karoo Fresh Holdings Ltd", "contactPhone": "+27 82 555 0143", "instructions": "Budget deferred to the next financial year.", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "arrivedAt": "2026-09-01T09:15:00Z", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyOrdered": 1.0, "qtyDelivered": 1.0, "uom": "each", "batchNumber": "INV-0001", "productBarcode": "6001234567890", "qtyLoaded": 1.0, "service": false } ], "hasProof": false, "collectable": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "amountDue": 10005.0, "foreignCurrency": "ZAR" }, "collection": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "paymentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 10005.0, "method": "cash", "reference": "INV-0001", "collectedAt": "2026-09-01T09:15:00Z", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "bankedAt": "2026-09-01T09:15:00Z", "bankingId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } ], "stopsTotal": 42, "stopsRemaining": 1, "preTripChecklist": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd" } ], "preTripState": "sent", "preTripBlocker": "text" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/trips/{id}": { "get": { "tags": [ "Driver app API" ], "summary": "One manifest.", "operationId": "getDriverApiV1TripsById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDriverApiV1TripsByIdResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "tripDate": "2026-09-01", "status": "sent", "routeName": "Karoo Fresh Holdings Ltd", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "plannedDeparture": "text", "startOdometerKm": 1.0, "notes": "Budget deferred to the next financial year.", "stops": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "sequence": 1, "stopType": "standard", "status": "sent", "customerName": "Karoo Fresh Holdings Ltd", "documentNumber": "INV-0001", "address": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "latitude": 1.0, "longitude": 1.0, "contactName": "Karoo Fresh Holdings Ltd", "contactPhone": "+27 82 555 0143", "instructions": "Budget deferred to the next financial year.", "windowFrom": "2026-09-01", "windowTo": "2026-09-30", "arrivedAt": "2026-09-01T09:15:00Z", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "description": "Consulting services — August 2026", "qtyOrdered": 1.0, "qtyDelivered": 1.0, "uom": "each", "batchNumber": "INV-0001", "productBarcode": "6001234567890", "qtyLoaded": 1.0, "service": false } ], "hasProof": false, "collectable": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "amountDue": 10005.0, "foreignCurrency": "ZAR" }, "collection": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "stopId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001", "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "customerName": "Karoo Fresh Holdings Ltd", "paymentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 10005.0, "method": "cash", "reference": "INV-0001", "collectedAt": "2026-09-01T09:15:00Z", "driverId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "driverName": "Thandi Mokoena", "bankedAt": "2026-09-01T09:15:00Z", "bankingId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } ], "stopsTotal": 42, "stopsRemaining": 1, "preTripChecklist": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd" } ], "preTripState": "sent", "preTripBlocker": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/trips/{id}/start": { "post": { "tags": [ "Driver app API" ], "summary": "Depart, with the odometer the trip's distance is measured from.", "operationId": "postDriverApiV1TripsByIdStart", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "odometerKm": { "type": "number" }, "inspection": { "type": "object", "properties": { "clientReference": { "type": "string" }, "answers": { "type": "array", "items": { "$ref": "#/components/schemas/PostDriverApiV1TripsByIdStartRequestInspectionAnswersItem" } }, "at": { "type": "string" } } } } }, "example": { "odometerKm": 184320.0, "inspection": { "clientReference": "6d1f2a90-3b47-4e8c-9f05-1a7c2e4b8d36", "answers": [ { "itemId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Tyres and spare", "passed": true, "note": "Tread and pressure checked, spare inflated." } ], "at": "2026-09-01T09:15:00Z" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1StopsByIdProofResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostDriverApiV1StopsByIdProofResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/trips/{id}/complete": { "post": { "tags": [ "Driver app API" ], "summary": "Back at the depot. REFUSED while any stop still has no outcome — a trip closed with open stops leaves deliveries neither delivered nor failed, and therefore invisible to both the re-plan list and the failure report.", "operationId": "postDriverApiV1TripsByIdComplete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "odometerKm": { "type": "number" }, "fuelLitres": { "type": "number" }, "fuelCost": { "type": "number" } } }, "example": { "odometerKm": 184520.0, "fuelLitres": 62.4, "fuelCost": 1310.4 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1StopsByIdProofResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostDriverApiV1StopsByIdProofResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/stops/{id}/status": { "post": { "tags": [ "Driver app API" ], "summary": "Mark a stop en route or arrived. The fix at arrival is the first half of the evidence; the geofence allows the device's own claimed error, capped at 150m, because failing an honest driver in a yard with a bad sky view is how a business learns to ignore the flag.", "operationId": "postDriverApiV1StopsByIdStatus", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "accuracyM": { "type": "number" }, "at": { "type": "string" } } }, "example": { "status": "en_route", "latitude": 1.0, "longitude": 1.0, "accuracyM": 1.0, "at": "2026-09-01T09:15:00Z" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1StopsByIdProofResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostDriverApiV1StopsByIdProofResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/stops/{id}/proof": { "post": { "tags": [ "Driver app API" ], "summary": "The proof as one offline-safe unit — outcome, receiver, quantities and the drawn signature in a single request. Send the same clientReference on a retry and the STORED proof comes back rather than a second one. captured_at is your clock, recorded_at is the server's; both are kept.", "operationId": "postDriverApiV1StopsByIdProof", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1StopsByIdProofRequest" }, "examples": { "default": { "$ref": "#/components/examples/PostDriverApiV1StopsByIdProofRequestExample" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1StopsByIdProofResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostDriverApiV1StopsByIdProofResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/stops/{id}/proof/photos": { "post": { "tags": [ "Driver app API" ], "summary": "Attach a photograph to the proof just recorded. Raw image bytes as the body, ?caption= for the label. Send ?clientId= (the id the phone minted for the photograph when it was taken): the first upload answers 201, a retry 200 with the photograph already stored, and an id already used by another proof — or by another business — is refused. ?proofReference= (the proof's clientReference) refuses it when the stop's proof is a different capture.", "operationId": "postDriverApiV1StopsByIdProofPhotos", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "caption", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Serial%20plate%20before%20fitting" }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "proofReference", "in": "query", "required": false, "schema": { "type": "string" }, "example": "proofReference" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpForecastsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/trips/{id}/messages": { "get": { "tags": [ "Driver app API" ], "summary": "The thread with the office for one of this driver's trips, in the order written. Reading it marks the office's messages delivered. Any trip that is not this driver's answers 404.", "operationId": "getDriverApiV1TripsByIdMessages", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDriverApiV1TripsByIdMessagesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetDriverApiV1TripsByIdMessagesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Driver app API" ], "summary": "Write to the office. Idempotent on id, so a message held on the phone in a dead zone lands once however often it is retried (201 new, 200 replay), in the place writtenAt and clientSeq put it. The office is pushed once, unless it has switched driver messages off.", "operationId": "postDriverApiV1TripsByIdMessages", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1TripsByIdMessagesRequest" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "body": "What is the gate code?", "clientSeq": 1, "writtenAt": "2026-10-12T08:00:00+02:00" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1TripsByIdMessagesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostDriverApiV1TripsByIdMessagesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/trips/{id}/messages/photo": { "post": { "tags": [ "Driver app API" ], "summary": "A photo for the office, as a message. Raw image bytes as the body; id, clientSeq, writtenAt and caption on the query. Sent only with signal: the phone does not hold photographs for a message.", "operationId": "postDriverApiV1TripsByIdMessagesPhoto", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "clientSeq", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" }, { "name": "writtenAt", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-10-12T08%3A00%3A00%2B02%3A00" }, { "name": "caption", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Gate" } ], "responses": { "201": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/trips/{id}/messages/read": { "post": { "tags": [ "Driver app API" ], "summary": "The driver opened the thread: the office's messages are read.", "operationId": "postDriverApiV1TripsByIdMessagesRead", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDriverApiV1TripsByIdMessagesReadResponse" }, "example": { "read": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/positions": { "post": { "tags": [ "Driver app API" ], "summary": "A batch of fixes, which is how a phone out of signal catches up. The vehicle comes from the driver's open trip and can never be named by the app.", "operationId": "postDriverApiV1Positions", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "positions": { "type": "array", "items": { "$ref": "#/components/schemas/PostDriverApiV1PositionsRequestPositionsItem" } } } }, "example": { "positions": [ { "latitude": -33.9249, "longitude": 18.4241, "accuracyM": 1.0, "speedKph": 48.0, "headingDeg": 1.0, "altitudeM": 1.0, "recordedAt": "2026-08-25T09:20:00Z", "batteryPercent": 62, "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "integer" }, "rejected": { "type": "integer" }, "reasons": { "type": "array", "items": { "type": "string" } } } }, "example": { "accepted": 1, "rejected": 0, "reasons": [ "Budget deferred to the next financial year." ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/driver-api/v1/exception-reasons": { "get": { "tags": [ "Driver app API" ], "summary": "The failure code list, for offline caching. A driver with no signal and no reason list types \"other\" into a notes field, and a year later the failure report is a reading exercise.", "operationId": "getDriverApiV1ExceptionReasons", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLogisticsExceptionReasonsResponse" } }, "examples": { "default": { "$ref": "#/components/examples/GetDriverApiV1ExceptionReasonsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/companies": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "Every entity under the tenant. This is the list X-Company-Id is chosen from.", "operationId": "getApiCompanies", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" }, { "name": "offset", "in": "query", "required": false, "description": "How many rows to skip. Use with `limit` to page. A paged response reports `total`, which is the number of rows matching the filter rather than the number returned.", "schema": { "type": "integer" }, "example": "0" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCompaniesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "parentCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "registrationNumber": "2021/123456/07", "vatNumber": "4123456789", "vatCategory": "Office supplies", "taxNumber": "9012345678", "payeNumber": "INV-0001", "uifNumber": "INV-0001", "sdlNumber": "INV-0001", "tradingAs": "text", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "address": "12 Long Street, Cape Town, 8001", "companyType": "PTY", "fiscalYearEndMonth": 9, "baseCurrency": "ZAR", "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "hasPostedLedger": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Multi-company & consolidation" ], "summary": "Add an entity. Enterprise and Manufacturing include two; a further one is the extra-company add-on. Company number one is never charged for, and a module you have unlocked applies to EVERY entity rather than being charged again on each. The allowance is checked at CREATE only — a tenant already over it keeps every entity and can go on working in all of them; only a new one is refused, with 409 COMPANY_LIMIT_REACHED.", "operationId": "postApiCompanies", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customsCode": { "type": "string" }, "payrollContactFirstName": { "type": "string" }, "payrollContactSurname": { "type": "string" }, "payrollContactPhone": { "type": "string" }, "payrollContactCell": { "type": "string" }, "vatApportionmentPercent": { "type": "number" }, "vatApportionmentFrom": { "type": "string", "format": "date" }, "gs1Prefix": { "type": "string" }, "name": { "type": "string" }, "registrationNumber": { "type": "string" }, "incorporationDate": { "type": "string", "format": "date" }, "vatNumber": { "type": "string" }, "vatCategory": { "type": "string" }, "taxNumber": { "type": "string" }, "payeNumber": { "type": "string" }, "uifNumber": { "type": "string" }, "sdlNumber": { "type": "string" }, "sic7Code": { "type": "string" }, "pboApproved": { "type": "boolean" }, "pboReference": { "type": "null" }, "s18aApproved": { "type": "boolean" }, "specialTrust": { "type": "boolean" }, "tradingAs": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "streetAddress": { "type": "string" }, "suburb": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "companyType": { "type": "string" }, "fiscalYearEndMonth": { "type": "integer" }, "baseCurrency": { "type": "string" }, "parentCompanyId": { "type": "string" }, "ownershipPercent": { "type": "number" }, "consolidationMethod": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "customsCode": "CC0012345", "payrollContactFirstName": "Lerato", "payrollContactSurname": "Molefe", "payrollContactPhone": "0214441234", "payrollContactCell": "0821234567", "vatApportionmentPercent": 80.0, "vatApportionmentFrom": "2026-10-01", "gs1Prefix": "6001234", "name": "KMP Cloud (Pty) Ltd", "registrationNumber": "2021/123456/07", "incorporationDate": "2021-03-15", "vatNumber": "4123456789", "vatCategory": "Office supplies", "taxNumber": "9012345678", "payeNumber": "INV-0001", "uifNumber": "INV-0001", "sdlNumber": "INV-0001", "sic7Code": "62010", "pboApproved": false, "pboReference": null, "s18aApproved": false, "specialTrust": false, "tradingAs": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "address": "12 Long Street, Cape Town, 8001", "streetAddress": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "companyType": "PTY", "fiscalYearEndMonth": 2, "baseCurrency": "ZAR", "parentCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownershipPercent": 15.0, "consolidationMethod": "FULL", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCompaniesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCompaniesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/companies/{id}": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "One entity.", "operationId": "getApiCompaniesById", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCompaniesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCompaniesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Multi-company & consolidation" ], "summary": "Update an entity.", "operationId": "putApiCompaniesById", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tradingCurrency": { "type": "string" }, "customsCode": { "type": "string" }, "payrollContactFirstName": { "type": "string" }, "payrollContactSurname": { "type": "string" }, "payrollContactPhone": { "type": "string" }, "payrollContactCell": { "type": "string" }, "sharesInventory": { "type": "boolean" }, "sharesPeople": { "type": "boolean" }, "vatApportionmentPercent": { "type": "number" }, "vatApportionmentFrom": { "type": "string", "format": "date" }, "gs1Prefix": { "type": "string" }, "name": { "type": "string" }, "registrationNumber": { "type": "string" }, "incorporationDate": { "type": "string", "format": "date" }, "sdlExemption": { "type": "null" }, "sdlExemptionReference": { "type": "null" }, "vatNumber": { "type": "string" }, "vatCategory": { "type": "string" }, "taxNumber": { "type": "string" }, "payeNumber": { "type": "string" }, "uifNumber": { "type": "string" }, "sdlNumber": { "type": "string" }, "sic7Code": { "type": "string" }, "pboApproved": { "type": "boolean" }, "pboReference": { "type": "null" }, "s18aApproved": { "type": "boolean" }, "specialTrust": { "type": "boolean" }, "tradingAs": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "streetAddress": { "type": "string" }, "suburb": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "companyType": { "type": "string" }, "fiscalYearEndMonth": { "type": "integer" }, "baseCurrency": { "type": "string" }, "isActive": { "type": "boolean" }, "parentCompanyId": { "type": "string" }, "ownershipPercent": { "type": "number" }, "consolidationMethod": { "type": "string" } } }, "example": { "tradingCurrency": "EUR", "customsCode": "CC0012345", "payrollContactFirstName": "Lerato", "payrollContactSurname": "Molefe", "payrollContactPhone": "0214441234", "payrollContactCell": "0821234567", "sharesInventory": true, "sharesPeople": false, "vatApportionmentPercent": 80.0, "vatApportionmentFrom": "2026-10-01", "gs1Prefix": "6001234", "name": "KMP Cloud (Pty) Ltd", "registrationNumber": "2021/123456/07", "incorporationDate": "2021-03-15", "sdlExemption": null, "sdlExemptionReference": null, "vatNumber": "4123456789", "vatCategory": "Office supplies", "taxNumber": "9012345678", "payeNumber": "INV-0001", "uifNumber": "INV-0001", "sdlNumber": "INV-0001", "sic7Code": "62010", "pboApproved": false, "pboReference": null, "s18aApproved": false, "specialTrust": false, "tradingAs": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "phone": "+27 82 555 0143", "address": "12 Long Street, Cape Town, 8001", "streetAddress": "12 Long Street, Cape Town, 8001", "suburb": "Woodstock", "city": "Cape Town", "postalCode": "CT-001", "companyType": "PTY", "fiscalYearEndMonth": 9, "baseCurrency": "ZAR", "isActive": true, "parentCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownershipPercent": 15.0, "consolidationMethod": "FULL" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCompaniesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiCompaniesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Multi-company & consolidation" ], "summary": "Remove an entity.", "operationId": "deleteApiCompaniesById", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/companies/{id}/partners": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "A partnership's partners, their profit shares, largest first, and the annual salary and interest on capital each is allocated before the rest is shared, with the shares' exact total. Any other legal form answers an empty list with partnership=false. Needs multicompany:view, and a company the caller may open.", "operationId": "getApiCompaniesByIdPartners", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string" }, "partnership": { "type": "boolean" }, "partners": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "idNumber": { "type": "string" }, "taxNumber": { "type": "string" }, "sharePercent": { "type": "number" }, "effectiveFrom": { "type": "string", "format": "date" }, "salary": { "type": "number" }, "interestOnCapital": { "type": "number" } } } }, "totalPercent": { "type": "number" } } }, "example": { "companyId": "7f6c1a2e-0000-4000-8000-000000000010", "partnership": true, "partners": [ { "id": "7f6c1a2e-0000-4000-8000-000000000011", "name": "Thandi Dlamini", "idNumber": "8001015009087", "taxNumber": "0123456789", "sharePercent": 60.0, "effectiveFrom": "2026-03-01", "salary": 240000.0, "interestOnCapital": 12000.0 }, { "id": "7f6c1a2e-0000-4000-8000-000000000012", "name": "Pieter Venter", "sharePercent": 40.0, "effectiveFrom": "2026-03-01", "salary": 180000.0, "interestOnCapital": 0.0 } ], "totalPercent": 100.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Multi-company & consolidation" ], "summary": "Replace a partnership's partners with this whole list. A partner sent with their id keeps it (their ITR12 schedule link stays good); one left out is removed. Refused (400, naming the sum) unless there are at least two partners whose shares add up to exactly 100; refused (409) for a company that is not a partnership. `salary` and `interestOnCapital` (annual rand, default 0, never negative) are allocated to the partner before the rest of the profit or loss is shared by the ratio (Income Tax Act s24H(5)(a)); each partner's ITR12 schedule carries them. `effectiveFrom` defaults to today. Needs multicompany:edit.", "operationId": "putApiCompaniesByIdPartners", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partners": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "taxNumber": { "type": "string" }, "sharePercent": { "type": "number" }, "salary": { "type": "number" }, "interestOnCapital": { "type": "number" } } } }, "effectiveFrom": { "type": "string", "format": "date" } } }, "example": { "partners": [ { "name": "Thandi Dlamini", "taxNumber": "0123456789", "sharePercent": 60.0, "salary": 240000.0, "interestOnCapital": 12000.0 }, { "name": "Pieter Venter", "sharePercent": 40.0, "salary": 180000.0 } ], "effectiveFrom": "2026-03-01" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string" }, "partnership": { "type": "boolean" }, "partners": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "taxNumber": { "type": "string" }, "sharePercent": { "type": "number" }, "effectiveFrom": { "type": "string", "format": "date" }, "salary": { "type": "number" }, "interestOnCapital": { "type": "number" } } } }, "totalPercent": { "type": "number" } } }, "example": { "companyId": "7f6c1a2e-0000-4000-8000-000000000010", "partnership": true, "partners": [ { "id": "7f6c1a2e-0000-4000-8000-000000000011", "name": "Thandi Dlamini", "taxNumber": "0123456789", "sharePercent": 60.0, "effectiveFrom": "2026-03-01", "salary": 240000.0, "interestOnCapital": 12000.0 }, { "id": "7f6c1a2e-0000-4000-8000-000000000012", "name": "Pieter Venter", "sharePercent": 40.0, "effectiveFrom": "2026-03-01", "salary": 180000.0, "interestOnCapital": 0.0 } ], "totalPercent": 100.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/companies/{id}/users": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "Who may act in this entity.", "operationId": "getApiCompaniesByIdUsers", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiCompaniesByIdUsersResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "role": "Accountant", "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "hasPostedLedger": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Multi-company & consolidation" ], "summary": "Grant a user access to this entity. An EMPTY company_users set grants — an owner whose assignments were never seeded must not be locked out.", "operationId": "postApiCompaniesByIdUsers", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "role": { "type": "string" }, "roleId": { "type": "string" } } }, "example": { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "role": "VIEWER", "roleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiCompaniesByIdUsersResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "role": "Accountant", "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "hasPostedLedger": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/companies/{id}/users/{userId}/role": { "put": { "tags": [ "Multi-company & consolidation" ], "summary": "Set a user's role in this entity, or clear it with a null roleId to return them to their organisation role. Needs roles:edit. The owner, the caller and an unassigned user are refused.", "operationId": "putApiCompaniesByIdUsersByUserIdRole", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiUsersByIdTransferOwnershipRequest" }, "example": { "roleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hasPostedLedger": { "type": "boolean" }, "roleId": { "type": "string" }, "roleName": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "role": "MEMBER", "isActive": true, "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z", "hasPostedLedger": false, "roleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "roleName": "Viewer" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/companies/{id}/users/{userId}": { "delete": { "tags": [ "Multi-company & consolidation" ], "summary": "Lift a person's restriction to this entity. Removing their last assignment returns them to every entity in the organisation, and the audit record says so. 404 when they are not restricted to it.", "operationId": "deleteApiCompaniesByIdUsersByUserId", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sandbox": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "The API sandbox: a company of sample data inside your own account, for trying the API without touching your real books. Null when you have none. It comes with API access, so it is available only on a plan that includes API keys; available and refusal say whether yours does. The rule is stated in the answer — a sandbox is not counted against the company allowance, you may have one at a time, its name cannot be changed, and it is marked Sandbox wherever it appears.", "operationId": "getApiSandbox", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sandbox": { "$ref": "#/components/schemas/GetApiSandboxResponseSandbox" }, "rule": { "type": "string" }, "note": { "type": "string" }, "available": { "type": "boolean" }, "refusal": { "type": "null" } } }, "example": { "sandbox": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Sandbox — sample data", "label": "Sandbox — sample data", "createdAt": "2026-09-01T09:15:00Z" }, "rule": "A sandbox company does not count against your plan's company allowance. You may have one at a time; it is marked Sandbox wherever it appears, and deleting it removes every row it holds.", "note": "The sandbox is a separate company inside your own account, filled with sample customers, products and invoices that post to its own ledger.", "available": true, "refusal": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Multi-company & consolidation" ], "summary": "Create the sandbox once, seeded with three sample customers, two products and three invoices (paid, open, overdue) posted to its own ledger. Send its id as X-Company-Id to work in it. A second call answers the one you have with created false, rather than making another. Refused with 409 on a plan without API keys, naming the plan that includes them.", "operationId": "postApiSandbox", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sandbox": { "$ref": "#/components/schemas/GetApiSandboxResponseSandbox" }, "created": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "sandbox": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Sandbox — sample data", "label": "Sandbox — sample data", "createdAt": "2026-09-01T09:15:00Z" }, "created": true, "message": "Your sandbox is ready. Send its id as X-Company-Id to work in it." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Multi-company & consolidation" ], "summary": "Delete the sandbox in one step, with every row it holds and nothing of your real company's. Refused with 409, and nothing deleted, if a record in a real company points at a sandbox record; the refusal names the records that block it.", "operationId": "deleteApiSandbox", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deletedRows": { "type": "integer" }, "keptContacts": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "deletedRows": 42, "keptContacts": 0, "message": "The sandbox and its 42 rows are gone." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/company-hierarchy/tree": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "The group structure as a tree, parent to subsidiary.", "operationId": "getApiCompanyHierarchyTree", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "rootId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "parentId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiCompanyHierarchyByIdParentResponse" } }, "tenantCompanyCount": { "type": "integer" }, "cyclicCompanyIds": { "type": "array", "items": { "type": "string" } }, "truncated": { "type": "boolean" } } }, "example": { "nodes": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "parentCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "tradeName": "Karoo Fresh Holdings Ltd", "companyType": "standard", "baseCurrency": "ZAR", "isActive": true, "depth": 1, "path": "text", "childCount": 3, "descendantCount": 3, "ownershipPercent": 15.0, "effectiveOwnershipPercent": 15.0, "consolidationMethod": "eft", "orphaned": false } ], "tenantCompanyCount": 3, "cyclicCompanyIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "truncated": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/company-hierarchy/picker": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "A searchable flat list for the entity switcher.", "operationId": "getApiCompanyHierarchyPicker", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search. What it covers differs per endpoint and is stated in the summary.", "schema": { "type": "string" }, "example": "cape" }, { "name": "offset", "in": "query", "required": false, "description": "How many rows to skip. Use with `limit` to page. A paged response reports `total`, which is the number of rows matching the filter rather than the number returned.", "schema": { "type": "integer" }, "example": "0" }, { "name": "includeInactive", "in": "query", "required": false, "description": "Include rows that have been deactivated. Deactivated is not deleted: it means \"stop offering this on new documents\".", "schema": { "type": "boolean" }, "example": "true" }, { "name": "parentId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiCompanyHierarchyPickerResponseItemsItem" } }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "hasMore": { "type": "boolean" } } }, "example": { "items": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "tradeName": "Karoo Fresh Holdings Ltd", "depth": 1, "breadcrumb": "text", "isActive": true, "baseCurrency": "ZAR", "childCount": 3 } ], "total": 42, "offset": 0, "limit": 50, "hasMore": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/company-hierarchy/{id}/ancestors": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "The chain from an entity up to the group head.", "operationId": "getApiCompanyHierarchyByIdAncestors", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string" }, "ancestors": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiCompanyHierarchyPickerResponseItemsItem" } }, "rootId": { "type": "string" }, "depth": { "type": "integer" } } }, "example": { "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ancestors": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "tradeName": "Karoo Fresh Holdings Ltd", "depth": 1, "breadcrumb": "text", "isActive": true, "baseCurrency": "ZAR", "childCount": 3 } ], "rootId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "depth": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/company-hierarchy/{id}/parent": { "put": { "tags": [ "Multi-company & consolidation" ], "summary": "Re-parent an entity. Refused if it would create a cycle.", "operationId": "putApiCompanyHierarchyByIdParent", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parentCompanyId": { "type": "string" }, "ownershipPercent": { "type": "number" }, "consolidationMethod": { "type": "string" } } }, "example": { "parentCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ownershipPercent": 15.0, "consolidationMethod": "eft" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiCompanyHierarchyByIdParentResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "parentCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "tradeName": "Karoo Fresh Holdings Ltd", "companyType": "standard", "baseCurrency": "ZAR", "isActive": true, "depth": 1, "path": "text", "childCount": 3, "descendantCount": 3, "ownershipPercent": 15.0, "effectiveOwnershipPercent": 15.0, "consolidationMethod": "eft", "orphaned": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/company-hierarchy/repair": { "post": { "tags": [ "Multi-company & consolidation" ], "summary": "Repair an inconsistent hierarchy — orphans and broken depth values.", "operationId": "postApiCompanyHierarchyRepair", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "companiesScanned": { "type": "integer" }, "pathsRewritten": { "type": "integer" }, "cyclicCompanyIds": { "type": "array", "items": { "type": "string" } }, "orphanedCompanyIds": { "type": "array", "items": { "type": "string" } } } }, "example": { "companiesScanned": 1, "pathsRewritten": 1, "cyclicCompanyIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "orphanedCompanyIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/company-hierarchy/{id}/consolidated/income-statement": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "Consolidated income statement at ANY node of the tree, not only the group head. The lines are the figures after eliminations. A foreign subsidiary's income and expenses are translated at the rate of the day each was posted (IFRS for SMEs 30.18); translationNotice names the closing rates used.", "operationId": "getApiCompanyHierarchyByIdConsolidatedIncomeStatement", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseScope" }, "periodLabel": { "type": "string" }, "presentationCurrency": { "type": "string" }, "combinedRevenue": { "type": "number" }, "combinedCostOfSales": { "type": "number" }, "combinedOperatingExpenses": { "type": "number" }, "eliminatedIntercompanyTurnover": { "type": "number" }, "consolidatedRevenue": { "type": "number" }, "consolidatedCostOfSales": { "type": "number" }, "consolidatedOperatingExpenses": { "type": "number" }, "consolidatedGrossProfit": { "type": "number" }, "consolidatedOperatingProfit": { "type": "number" }, "taxExpense": { "type": "number" }, "consolidatedProfitAfterTax": { "type": "number" }, "profitAttributableToOwners": { "type": "number" }, "profitAttributableToNonControlling": { "type": "number" }, "revenueLines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "costOfSalesLines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "operatingExpenseLines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "nonControllingInterest": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseNonControllingInterest" } } }, "example": { "scope": { "rootCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rootName": "Karoo Fresh Holdings Ltd", "companyIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "companyCount": 3, "excluded": [ { "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year." } ], "maxDepth": 1 }, "periodLabel": "2026-09", "presentationCurrency": "ZAR", "combinedRevenue": 1.0, "combinedCostOfSales": 10005.0, "combinedOperatingExpenses": 1.0, "eliminatedIntercompanyTurnover": 1.0, "consolidatedRevenue": 1.0, "consolidatedCostOfSales": 10005.0, "consolidatedOperatingExpenses": 1.0, "consolidatedGrossProfit": 1.0, "consolidatedOperatingProfit": 1.0, "taxExpense": 1305.0, "consolidatedProfitAfterTax": 1305.0, "profitAttributableToOwners": 1.0, "profitAttributableToNonControlling": 1.0, "revenueLines": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "costOfSalesLines": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "operatingExpenseLines": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "nonControllingInterest": { "shareOfProfit": 1.0, "shareOfNetAssets": 8700.0, "perEntity": [ { "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "effectiveOwnershipPercent": 15.0, "nonControllingPercent": 15.0, "standaloneProfit": 1.0, "standaloneNetAssets": 8700.0, "nonControllingProfit": 1.0, "nonControllingNetAssets": 8700.0 } ], "whollyOwnedGroup": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/company-hierarchy/{id}/consolidated/balance-sheet": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "Consolidated balance sheet at any node. The lines are the figures after eliminations and add up to the totals. A foreign subsidiary's assets and liabilities are translated at the closing rate of asOf, its equity at historical rates, and the difference is the translation reserve in equity; translationNotice names each closing rate with its date and source.", "operationId": "getApiCompanyHierarchyByIdConsolidatedBalanceSheet", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asOf", "in": "query", "required": false, "description": "Re-derive the position at this date rather than today, as `YYYY-MM-DD`. Settlements after it are reversed out, so the answer ties to a balance sheet at the same date. An unparseable date is refused, never defaulted to today.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseScope" }, "asOfLabel": { "type": "string" }, "presentationCurrency": { "type": "string" }, "nonCurrentAssets": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "currentAssets": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "nonCurrentLiabilities": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "currentLiabilities": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "equityLines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "combinedTotalAssets": { "type": "number" }, "combinedTotalLiabilities": { "type": "number" }, "eliminatedIntercompanyBalances": { "type": "number" }, "consolidatedTotalAssets": { "type": "number" }, "consolidatedTotalLiabilities": { "type": "number" }, "consolidatedNetAssets": { "type": "number" }, "equityAttributableToOwners": { "type": "number" }, "nonControllingInterestEquity": { "type": "number" }, "nonControllingInterest": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseNonControllingInterest" }, "balancingDifference": { "type": "number" }, "eliminatedInvestment": { "type": "number" }, "eliminatedSubsidiaryCapital": { "type": "number" }, "goodwill": { "type": "number" }, "bargainPurchaseGain": { "type": "number" }, "investmentNotice": { "type": "string" } } }, "example": { "scope": { "rootCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rootName": "Karoo Fresh Holdings Ltd", "companyIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "companyCount": 3, "excluded": [ { "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year." } ], "maxDepth": 1 }, "asOfLabel": "Karoo Fresh Holdings Ltd", "presentationCurrency": "ZAR", "nonCurrentAssets": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "currentAssets": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "nonCurrentLiabilities": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "currentLiabilities": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "equityLines": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "combinedTotalAssets": 10005.0, "combinedTotalLiabilities": 10005.0, "eliminatedIntercompanyBalances": 10005.0, "consolidatedTotalAssets": 10005.0, "consolidatedTotalLiabilities": 10005.0, "consolidatedNetAssets": 8700.0, "equityAttributableToOwners": 1.0, "nonControllingInterestEquity": 1.0, "nonControllingInterest": { "shareOfProfit": 1.0, "shareOfNetAssets": 8700.0, "perEntity": [ { "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "effectiveOwnershipPercent": 15.0, "nonControllingPercent": 15.0, "standaloneProfit": 1.0, "standaloneNetAssets": 8700.0, "nonControllingProfit": 1.0, "nonControllingNetAssets": 8700.0 } ], "whollyOwnedGroup": true }, "balancingDifference": 1.0, "eliminatedInvestment": 60000.0, "eliminatedSubsidiaryCapital": 60000.0, "goodwill": 0.0, "bargainPurchaseGain": 0.0, "investmentNotice": "The investment of R60 000.00 is set against the group's share of the subsidiaries' share capital as their books hold it at this date." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/company-hierarchy/{id}/consolidated/trial-balance": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "Consolidated trial balance at any node. Each row is the figure after eliminations (eliminationDebit and eliminationCredit say how much of it is an elimination) and the foreign currency translation reserve (3550) balances the translated subsidiaries.", "operationId": "getApiCompanyHierarchyByIdConsolidatedTrialBalance", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseScope" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "periodLabel": { "type": "string" }, "presentationCurrency": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "accountType": { "type": "string" }, "openingBalance": { "type": "number" }, "debit": { "type": "number" }, "credit": { "type": "number" }, "closingBalance": { "type": "number" }, "closingDebit": { "type": "number" }, "closingCredit": { "type": "number" }, "contributingCompanies": { "type": "integer" } } } }, "totalDebit": { "type": "number" }, "totalCredit": { "type": "number" }, "totalClosingDebit": { "type": "number" }, "totalClosingCredit": { "type": "number" }, "balanced": { "type": "boolean" }, "empty": { "type": "boolean" }, "eliminations": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedEliminationsResponse" } } }, "example": { "scope": { "rootCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rootName": "Karoo Fresh Holdings Ltd", "companyIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "companyCount": 3, "excluded": [ { "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year." } ], "maxDepth": 1 }, "from": "2026-09-01", "to": "2026-09-30", "periodLabel": "2026-09", "presentationCurrency": "ZAR", "rows": [ { "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "accountType": "asset", "openingBalance": 10005.0, "debit": 1.0, "credit": 1.0, "closingBalance": 10005.0, "closingDebit": 1.0, "closingCredit": 1.0, "contributingCompanies": 1 } ], "totalDebit": 10005.0, "totalCredit": 10005.0, "totalClosingDebit": 10005.0, "totalClosingCredit": 10005.0, "balanced": true, "empty": true, "eliminations": { "scope": { "rootCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rootName": "Karoo Fresh Holdings Ltd", "companyIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "companyCount": 3, "excluded": [ { "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year." } ], "maxDepth": 1 }, "eliminated": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromName": "Karoo Fresh Holdings Ltd", "toCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toName": "Karoo Fresh Holdings Ltd", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "open": true } ], "external": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromName": "Karoo Fresh Holdings Ltd", "toCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toName": "Karoo Fresh Holdings Ltd", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "open": true } ], "eliminatedTurnover": 1.0, "eliminatedBalances": 10005.0, "externalTurnover": 1.0 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/company-hierarchy/{id}/consolidated/eliminations": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "The inter-company eliminations applied, line by line.", "operationId": "getApiCompanyHierarchyByIdConsolidatedEliminations", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedEliminationsResponse" }, "example": { "scope": { "rootCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "rootName": "Karoo Fresh Holdings Ltd", "companyIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "companyCount": 3, "excluded": [ { "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "reason": "Budget deferred to the next financial year." } ], "maxDepth": 1 }, "eliminated": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromName": "Karoo Fresh Holdings Ltd", "toCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toName": "Karoo Fresh Holdings Ltd", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "open": true } ], "external": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromName": "Karoo Fresh Holdings Ltd", "toCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toName": "Karoo Fresh Holdings Ltd", "date": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "open": true } ], "eliminatedTurnover": 1.0, "eliminatedBalances": 10005.0, "externalTurnover": 1.0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/intercompany-transactions": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "The inter-company transaction log.", "operationId": "getApiIntercompanyTransactions", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "open" }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiIntercompanyTransactionsByIdResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "transactionDate": "2026-09-01", "description": "Consulting services — August 2026", "amount": 10005.0, "currency": "ZAR", "exchangeRate": 1.0, "accountIdFrom": "2026-09-01", "accountIdTo": "2026-09-30", "status": "PENDING", "settledOn": "2026-09-01", "settledAt": "2026-09-01T09:15:00Z", "settledByName": "Karoo Fresh Holdings Ltd", "settlementReference": "INV-0001", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Multi-company & consolidation" ], "summary": "Record an inter-company transaction. `kind` says what the amount is: trade (a sale or service, the default), loan or dividend. A loan or dividend is a balance between the two companies and is never eliminated as turnover; a sale is eliminated net of VAT. For a sale of goods, `sellerCost` (what the goods cost the seller) and `buyerHeldPercent` (0-100, the share the buyer still holds) let consolidation eliminate the unrealised profit from inventory and group profit. For a sale of equipment, `buyerAssetId` (the asset in the buyer's register) with `sellerCost` (the seller's carrying amount) lets consolidation eliminate the gain and the depreciation charged on it.", "operationId": "postApiIntercompanyTransactions", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiIntercompanyTransactionsRequest" }, "example": { "fromCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "transactionDate": "2026-08-31", "description": "Management fee", "amount": 85000.0, "currency": "ZAR", "exchangeRate": 1.0, "accountIdFrom": "2026-09-01", "accountIdTo": "2026-09-30", "kind": "trade", "sellerCost": 60000.0, "buyerHeldPercent": 100.0, "buyerAssetId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiIntercompanyTransactionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiIntercompanyTransactionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/intercompany-transactions/{id}": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "One transaction.", "operationId": "getApiIntercompanyTransactionsById", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiIntercompanyTransactionsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiIntercompanyTransactionsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Multi-company & consolidation" ], "summary": "Correct a transaction. Every field is replaced; an eliminated transaction is refused. Omit `kind` to keep the transaction's kind; a transaction that mirrors an invoice or records a bank payment cannot change it.", "operationId": "putApiIntercompanyTransactionsById", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiIntercompanyTransactionsRequest" }, "example": { "fromCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "transactionDate": "2026-08-27", "description": "Management fee - corrected", "amount": 90000.0, "currency": "ZAR", "exchangeRate": 1.0, "accountIdFrom": "2026-09-01", "accountIdTo": "2026-09-30", "kind": "trade", "sellerCost": 60000.0, "buyerHeldPercent": 100.0, "buyerAssetId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiIntercompanyTransactionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiIntercompanyTransactionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Multi-company & consolidation" ], "summary": "Delete a transaction.", "operationId": "deleteApiIntercompanyTransactionsById", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/intercompany-transactions/{id}/match": { "post": { "tags": [ "Multi-company & consolidation" ], "summary": "Agree both legs of a transaction. PENDING only.", "operationId": "postApiIntercompanyTransactionsByIdMatch", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthLogoutResponse" }, "example": { "message": "Transaction matched" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/intercompany-transactions/{id}/settle": { "post": { "tags": [ "Multi-company & consolidation" ], "summary": "Eliminate an inter-company transaction for consolidation. MATCHED only. Wire alias of /{id}/eliminate; it does NOT record that one entity paid another - that is POST /{id}/payment.", "operationId": "postApiIntercompanyTransactionsByIdSettle", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthLogoutResponse" }, "example": { "message": "Transaction eliminated" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/intercompany-transactions/{id}/eliminate": { "post": { "tags": [ "Multi-company & consolidation" ], "summary": "Eliminate an inter-company transaction for consolidation. MATCHED only.", "operationId": "postApiIntercompanyTransactionsByIdEliminate", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthLogoutResponse" }, "example": { "message": "Transaction eliminated" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/intercompany-transactions/{id}/payment": { "post": { "tags": [ "Multi-company & consolidation" ], "summary": "Record that one entity actually paid another. Separate from elimination - an amount is often eliminated and still unpaid.", "operationId": "postApiIntercompanyTransactionsByIdPayment", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paidOn": { "type": "string", "format": "date" }, "reference": { "type": "string" } } }, "example": { "paidOn": "2026-08-25", "reference": "EFT 4471" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiIntercompanyTransactionsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiIntercompanyTransactionsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Multi-company & consolidation" ], "summary": "Remove a payment record. Always permitted, so a mis-keyed settlement is correctable.", "operationId": "deleteApiIntercompanyTransactionsByIdPayment", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiIntercompanyTransactionsByIdResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiIntercompanyTransactionsByIdResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/intercompany-transactions/eliminate-all": { "post": { "tags": [ "Multi-company & consolidation" ], "summary": "Eliminate every matched transaction for a period in one pass.", "operationId": "postApiIntercompanyTransactionsEliminateAll", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiFixedAssetsDepreciationRunRequest" }, "example": { "period": "2026-08" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "eliminated": { "type": "integer" } } }, "example": { "eliminated": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/consolidation-groups": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "Consolidation groups and their members.", "operationId": "getApiConsolidationGroups", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiConsolidationGroupsResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "rootCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "baseCurrency": "ZAR", "reportingPeriodStart": "2026-09-01", "reportingPeriodEnd": "2026-09-30", "status": "DRAFT", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Multi-company & consolidation" ], "summary": "Define a consolidation group.", "operationId": "postApiConsolidationGroups", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "baseCurrency": { "type": "string" }, "reportingPeriodStart": { "type": "string", "format": "date" }, "reportingPeriodEnd": { "type": "string", "format": "date" }, "rootCompanyId": { "type": "string" }, "clientId": { "type": "string" } } }, "example": { "name": "KMP Group", "baseCurrency": "ZAR", "reportingPeriodStart": "2026-09-01", "reportingPeriodEnd": "2026-09-30", "rootCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiConsolidationGroupsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiConsolidationGroupsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/consolidation-groups/{id}": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "One group.", "operationId": "getApiConsolidationGroupsById", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiConsolidationGroupsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiConsolidationGroupsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Multi-company & consolidation" ], "summary": "Delete a group.", "operationId": "deleteApiConsolidationGroupsById", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/consolidation-groups/{id}/run": { "post": { "tags": [ "Multi-company & consolidation" ], "summary": "Run the consolidation and store the result.", "operationId": "postApiConsolidationGroupsByIdRun", "description": "Requires the `multi-company:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asAt": { "type": "string", "format": "date" } } }, "example": { "asAt": "2027-02-28" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "groupId": { "type": "string" }, "eliminationsPosted": { "type": "integer" } } }, "example": { "message": "Consolidation finalised", "groupId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "eliminationsPosted": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/consolidation-groups/{id}/entries": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "The consolidation entries produced by a run.", "operationId": "getApiConsolidationGroupsByIdEntries", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "groupId": { "type": "string" }, "companyId": { "type": "string" }, "accountId": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "convertedAmount": { "type": "number" }, "exchangeRate": { "type": "number" }, "entryType": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "groupId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "amount": 10005.0, "currency": "ZAR", "convertedAmount": 10005.0, "exchangeRate": 1.0, "entryType": "STANDALONE", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/multi-company/overview": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "Per-entity dashboards — P&L summary, balance sheet and inter-company balances side by side.", "operationId": "getApiMultiCompanyOverview", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "financialYearLabel": { "type": "string" }, "entities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tradeName": { "type": "string" }, "registrationNumber": { "type": "string" }, "vatNumber": { "type": "string" }, "companyType": { "type": "string" }, "baseCurrency": { "type": "string" }, "isActive": { "type": "boolean" }, "isParent": { "type": "boolean" }, "parentId": { "type": "string" }, "colorHex": { "type": "string" }, "icon": { "type": "string" }, "financials": { "type": "object", "properties": { "revenue": { "type": "number" }, "cogs": { "type": "number" }, "opex": { "type": "number" }, "tax": { "type": "number" }, "assets": { "type": "number" }, "liabilities": { "type": "number" }, "equity": { "type": "number" }, "cash": { "type": "number" }, "debtors": { "type": "number" }, "creditors": { "type": "number" } } }, "interCo": { "type": "object", "properties": { "receivable": { "type": "number" }, "payable": { "type": "number" } } } } } }, "totals": { "type": "object", "properties": { "revenue": { "type": "number" }, "cogs": { "type": "number" }, "opex": { "type": "number" }, "tax": { "type": "number" }, "assets": { "type": "number" }, "liabilities": { "type": "number" }, "equity": { "type": "number" }, "cash": { "type": "number" }, "debtors": { "type": "number" }, "creditors": { "type": "number" }, "netProfit": { "type": "number" }, "interCoRevenueEliminated": { "type": "number" }, "interCoExpenseEliminated": { "type": "number" }, "interCoReceivablesEliminated": { "type": "number" }, "interCoPayablesEliminated": { "type": "number" }, "consolidatedRevenue": { "type": "number" }, "consolidatedAssets": { "type": "number" }, "consolidatedLiabilities": { "type": "number" }, "consolidatedNetProfit": { "type": "number" }, "pendingIcCount": { "type": "integer" } } } } }, "example": { "financialYearLabel": "Karoo Fresh Holdings Ltd", "entities": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "tradeName": "Karoo Fresh Holdings Ltd", "registrationNumber": "2021/123456/07", "vatNumber": "4123456789", "companyType": "standard", "baseCurrency": "ZAR", "isActive": true, "isParent": true, "parentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "colorHex": "#0D47A1", "icon": "text", "financials": { "revenue": 1.0, "cogs": 1.0, "opex": 1.0, "tax": 1305.0, "assets": 1.0, "liabilities": 1.0, "equity": 1.0, "cash": 1.0, "debtors": 1.0, "creditors": 1.0 }, "interCo": { "receivable": 1.0, "payable": 1.0 } } ], "totals": { "revenue": 1.0, "cogs": 1.0, "opex": 1.0, "tax": 1305.0, "assets": 1.0, "liabilities": 1.0, "equity": 1.0, "cash": 1.0, "debtors": 1.0, "creditors": 1.0, "netProfit": 8700.0, "interCoRevenueEliminated": 1.0, "interCoExpenseEliminated": 1.0, "interCoReceivablesEliminated": 1.0, "interCoPayablesEliminated": 1.0, "consolidatedRevenue": 1.0, "consolidatedAssets": 1.0, "consolidatedLiabilities": 1.0, "consolidatedNetProfit": 8700.0, "pendingIcCount": 3 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/multi-company/ic-matrix": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "The cross-entity outstanding balance matrix.", "operationId": "getApiMultiCompanyIcMatrix", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tradeName": { "type": "string" }, "colorHex": { "type": "string" } } } }, "cells": { "type": "array", "items": { "type": "object", "properties": { "fromCompanyId": { "type": "string" }, "fromTradeName": { "type": "string" }, "toCompanyId": { "type": "string" }, "toTradeName": { "type": "string" }, "pendingAmount": { "type": "number" } } } } } }, "example": { "companies": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tradeName": "Karoo Fresh Holdings Ltd", "colorHex": "#0D47A1" } ], "cells": [ { "fromCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "fromTradeName": "Karoo Fresh Holdings Ltd", "toCompanyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "toTradeName": "Karoo Fresh Holdings Ltd", "pendingAmount": 10005.0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/multi-company/shared-contacts": { "get": { "tags": [ "Multi-company & consolidation" ], "summary": "Contacts shared across entities, with a per-entity badge.", "operationId": "getApiMultiCompanySharedContacts", "description": "Requires the `multi-company:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "multi-company:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "contactType": { "type": "string" }, "sharedByCompanyIds": { "type": "array", "items": { "type": "string" } }, "sharedByTradeNames": { "type": "array", "items": { "type": "string" } } } } }, "example": [ { "name": "Karoo Fresh Holdings Ltd", "contactType": "customer", "sharedByCompanyIds": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "sharedByTradeNames": [ "Karoo Fresh Holdings Ltd" ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients": { "get": { "tags": [ "Accountant workspace" ], "summary": "The client console — every tenant this practitioner is linked to, most in need first: ordered by attentionScore (the sum of attentionWeights, one weight for each line of attentionItems; healthBand is on_track, watch or behind), a tie by client name.", "operationId": "getApiPractitionerClients", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "accessLevel": { "type": "string" }, "linkedSince": { "type": "string" }, "vatRegistered": { "type": "boolean" }, "openQueries": { "type": "integer" }, "draftJournals": { "type": "integer" }, "unreconciledTransactions": { "type": "integer" }, "lastPeriodClosed": { "type": "boolean" }, "lastClosedPeriod": { "type": "string" }, "payrollAwaitingPayment": { "type": "integer" }, "ledgerNotStarted": { "type": "boolean" }, "attentionItems": { "type": "array", "items": { "type": "string" } }, "payer": { "type": "string" }, "planId": { "type": "string" }, "planMonthlyRands": { "type": "number" }, "addonCentsMonthly": { "type": "integer" } } } }, "example": [ { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Karoo Fresh Holdings Ltd", "accessLevel": "text", "linkedSince": "text", "vatRegistered": false, "openQueries": 1, "draftJournals": 1, "unreconciledTransactions": 1, "lastPeriodClosed": false, "lastClosedPeriod": "2026-09", "payrollAwaitingPayment": 1, "ledgerNotStarted": false, "attentionItems": [ "text" ], "payer": "firm", "planId": "compliance", "planMonthlyRands": 1.0, "addonCentsMonthly": 49900 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Accountant workspace" ], "summary": "Place a Compliance client the practice pays for. Requires the Practice tier and roles:create.", "operationId": "postApiPractitionerClients", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "reference": { "type": "string" }, "planId": { "type": "string" }, "linkId": { "type": "string" }, "notice": { "type": "string" } } }, "example": { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Karoo Fresh Holdings Ltd", "reference": "INV-0001", "planId": "compliance", "linkId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notice": "This run includes a catch-up deduction; the year-to-date total is correct." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/adjusting-journals": { "get": { "tags": [ "Accountant workspace" ], "summary": "The console's review queue: the journals entered as drafts and not yet posted in the books of the clients the practice works on (links that show the bookkeeping workload), newest first, each naming its client. count and totalValue are the whole queue; journals is cut at limit. Requires the Practice tier and roles:view.", "operationId": "getApiPractitionerClientsAdjustingJournals", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "journals": { "type": "array", "items": { "type": "object", "properties": { "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "id": { "type": "string" }, "journalNumber": { "type": "string" }, "journalDate": { "type": "string", "format": "date" }, "sourceType": { "type": "string" }, "reference": { "type": "string" }, "memo": { "type": "string" }, "totalDebit": { "type": "number" }, "totalCredit": { "type": "number" }, "canOpen": { "type": "boolean" } } } }, "totalValue": { "type": "number" }, "count": { "type": "integer" } } }, "example": { "journals": [ { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Karoo Fresh Holdings Ltd", "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "journalNumber": "INV-0001", "journalDate": "2026-09-01", "sourceType": "manual", "reference": "INV-0001", "memo": "text", "totalDebit": 10005.0, "totalCredit": 10005.0, "canOpen": false } ], "totalValue": 10005.0, "count": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/deadlines": { "get": { "tags": [ "Accountant workspace" ], "summary": "Every SARS deadline across the practice's client book, soonest first — each client company's own deadline list. Requires the Practice tier.", "operationId": "getApiPractitionerDeadlines", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "companyName": { "type": "null" }, "clientReference": { "type": "string" }, "type": { "type": "string" }, "period": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "canOpenBooks": { "type": "boolean" } } } }, "example": [ { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Karoo Fresh Holdings Ltd", "companyName": null, "clientReference": "CUM-01", "type": "VAT201", "period": "Jul–Aug 2026", "dueDate": "2026-09-30", "canOpenBooks": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/links": { "get": { "tags": [ "Accountant workspace" ], "summary": "Practitioner links and their state.", "operationId": "getApiPractitionerLinks", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPractitionerLinksResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "practitionerEmail": "accounts@karoofresh.example", "practitionerName": "Karoo Fresh Holdings Ltd", "status": "sent", "accessLevel": "text", "invitedAt": "2026-09-01T09:15:00Z", "acceptedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Accountant workspace" ], "summary": "Invite a practitioner, or request access to a client.", "operationId": "postApiPractitionerLinks", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "accessLevel": { "type": "string" } } }, "example": { "email": "accountant@example.example", "name": "Karoo Fresh Holdings Ltd", "accessLevel": "full" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPractitionerLinksResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPractitionerLinksResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/links/{id}": { "patch": { "tags": [ "Accountant workspace" ], "summary": "Change the access a link gives (summary, full or books). A visit open in the books ends at once when books access is withdrawn.", "operationId": "patchApiPractitionerLinksById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchApiPractitionerLinksByIdRequest" }, "example": { "accessLevel": "books" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPractitionerLinksResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPractitionerLinksResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Accountant workspace" ], "summary": "End a link. Access stops immediately.", "operationId": "deleteApiPractitionerLinksById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/invitations": { "get": { "tags": [ "Accountant workspace" ], "summary": "Invitations waiting on this practitioner.", "operationId": "getApiPractitionerInvitations", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "practitionerEmail": { "type": "string" }, "practitionerName": { "type": "string" }, "status": { "type": "string" }, "accessLevel": { "type": "string" }, "invitedAt": { "type": "string" }, "acceptedAt": { "type": "string" }, "revokedAt": { "type": "string" }, "invitationEmailed": { "type": "boolean" }, "firmName": { "type": "string" }, "assignedStaff": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdStaffResponseRosterItem" } } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "practitionerEmail": "accounts@karoofresh.example", "practitionerName": "Karoo Fresh Holdings Ltd", "status": "invited", "accessLevel": "summary", "invitedAt": "2026-09-01T09:15:00Z", "acceptedAt": "2026-09-01T09:15:00Z", "revokedAt": "2026-09-01T09:15:00Z", "invitationEmailed": true, "firmName": "Karoo Fresh Holdings Ltd", "assignedStaff": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Karoo Fresh Holdings Ltd", "email": "accounts@karoofresh.example", "roleName": "Karoo Fresh Holdings Ltd", "isSelf": false } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/accept/{id}": { "post": { "tags": [ "Accountant workspace" ], "summary": "Accept an invitation.", "operationId": "postApiPractitionerAcceptById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPractitionerLinksResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPractitionerLinksResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/link-requests": { "get": { "tags": [ "Accountant workspace" ], "summary": "Every request this practice has sent a business to connect, with what became of each. Requires the Practice tier and roles:view.", "operationId": "getApiPractitionerLinkRequests", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "clientEmail": { "type": "string" }, "accessLevel": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "requestedByName": { "type": "string" }, "requestedByEmail": { "type": "string" }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" } } } }, "example": [ { "id": "7c2e4f10-9a3b-4d8e-b1f2-5a6c7d8e9f01", "clientEmail": "accounts@karoofresh.example", "accessLevel": "books", "message": "Following our meeting — please connect us so we can take over the year-end.", "status": "waiting", "requestedByName": "Thandi van Wyk", "requestedByEmail": "thandi@vanwyk.example", "createdAt": "2026-09-01T09:15:00Z", "expiresAt": "2026-10-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Accountant workspace" ], "summary": "Ask a business to connect to this practice. Answers identically whether or not the address belongs to anyone on Ledgr; a repeat to an address already waiting returns that request and sends nothing. Requires the Practice tier and roles:create.", "operationId": "postApiPractitionerLinkRequests", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "accessLevel": { "type": "string" }, "message": { "type": "string" } } }, "example": { "email": "accounts@karoofresh.example", "accessLevel": "books", "message": "Following our meeting — please connect us so we can take over the year-end." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "clientEmail": { "type": "string" }, "accessLevel": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "requestedByName": { "type": "string" }, "requestedByEmail": { "type": "string" }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" }, "emailed": { "type": "boolean" } } }, "example": { "id": "7c2e4f10-9a3b-4d8e-b1f2-5a6c7d8e9f01", "clientEmail": "accounts@karoofresh.example", "accessLevel": "books", "message": "Following our meeting — please connect us so we can take over the year-end.", "status": "waiting", "requestedByName": "Thandi van Wyk", "requestedByEmail": "thandi@vanwyk.example", "createdAt": "2026-09-01T09:15:00Z", "expiresAt": "2026-10-01T09:15:00Z", "emailed": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/link-requests/{id}/withdraw": { "post": { "tags": [ "Accountant workspace" ], "summary": "Withdraw a request that is still waiting. Requires the Practice tier and roles:create.", "operationId": "postApiPractitionerLinkRequestsByIdWithdraw", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "clientEmail": { "type": "string" }, "accessLevel": { "type": "string" }, "status": { "type": "string" }, "requestedByName": { "type": "string" }, "requestedByEmail": { "type": "string" }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" } } }, "example": { "id": "7c2e4f10-9a3b-4d8e-b1f2-5a6c7d8e9f01", "clientEmail": "accounts@karoofresh.example", "accessLevel": "books", "status": "withdrawn", "requestedByName": "Thandi van Wyk", "requestedByEmail": "thandi@vanwyk.example", "createdAt": "2026-09-01T09:15:00Z", "expiresAt": "2026-10-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/connection-requests": { "get": { "tags": [ "Accountant workspace" ], "summary": "Practices asking this business to connect — addressed to the caller, or to any of the business's people when the caller may answer. Every plan.", "operationId": "getApiPractitionerConnectionRequests", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "firmName": { "type": "string" }, "requestedByName": { "type": "string" }, "requestedByEmail": { "type": "string" }, "addressedTo": { "type": "string" }, "accessLevel": { "type": "string" }, "message": { "type": "string" }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" }, "mayRespond": { "type": "boolean" } } } }, "example": [ { "id": "7c2e4f10-9a3b-4d8e-b1f2-5a6c7d8e9f01", "firmName": "Van Wyk & Associates", "requestedByName": "Thandi van Wyk", "requestedByEmail": "thandi@vanwyk.example", "addressedTo": "accounts@karoofresh.example", "accessLevel": "books", "message": "Following our meeting — please connect us so we can take over the year-end.", "createdAt": "2026-09-01T09:15:00Z", "expiresAt": "2026-10-01T09:15:00Z", "mayRespond": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/connection-requests/{id}/accept": { "post": { "tags": [ "Accountant workspace" ], "summary": "Accept a practice's request at the level the business chooses, writing an active accountant link. Requires roles:create, as inviting an accountant does.", "operationId": "postApiPractitionerConnectionRequestsByIdAccept", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchApiPractitionerLinksByIdRequest" }, "example": { "accessLevel": "full" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "firmName": { "type": "string" }, "linkId": { "type": "string" }, "accessLevel": { "type": "string" }, "notice": { "type": "string" } } }, "example": { "id": "7c2e4f10-9a3b-4d8e-b1f2-5a6c7d8e9f01", "status": "accepted", "firmName": "Van Wyk & Associates", "linkId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accessLevel": "full", "notice": "Van Wyk & Associates is connected with Workload access. You can change or remove it under Settings → Accountant access at any time." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/connection-requests/{id}/decline": { "post": { "tags": [ "Accountant workspace" ], "summary": "Decline a practice's request. Nothing is shared. Requires roles:create.", "operationId": "postApiPractitionerConnectionRequestsByIdDecline", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "firmName": { "type": "string" }, "notice": { "type": "string" } } }, "example": { "id": "7c2e4f10-9a3b-4d8e-b1f2-5a6c7d8e9f01", "status": "declined", "firmName": "Van Wyk & Associates", "notice": "Declined. Nothing was shared with Van Wyk & Associates." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/queries": { "get": { "tags": [ "Accountant workspace" ], "summary": "In-app queries between practitioner and client, in place of an email thread nobody can find later.", "operationId": "getApiPractitionerQueries", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "open" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPractitionerQueriesResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subjectType": "standard", "subjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subjectLabel": "Karoo Fresh Holdings Ltd", "question": "text", "status": "sent", "priority": "normal", "answer": "text", "askedByEmail": "accounts@karoofresh.example", "createdAt": "2026-09-01T09:15:00Z", "answeredAt": "2026-09-01T09:15:00Z", "resolvedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Accountant workspace" ], "summary": "Raise a query, optionally against a specific transaction (subjectType bank with the line's id as subjectId). The client is emailed once when a practice raises one inside its books, unless it has switched 'Your accountant's questions' off, and reminded while it stays open: after 3 days, then weekly, at most 6 times. A client the practice placed (no user) is sent the address the practice holds for it, with a link that needs no account; a replay of the same clientId tells nobody twice.", "operationId": "postApiPractitionerQueries", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string" }, "subjectType": { "type": "string" }, "subjectId": { "type": "string" }, "subjectLabel": { "type": "string" }, "priority": { "type": "string" }, "clientId": { "type": "string" }, "kind": { "type": "string" }, "dueDate": { "type": "string", "format": "date" } } }, "example": { "question": "Please send the September bank statement.", "subjectType": "general", "subjectId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "subjectLabel": "Karoo Fresh Holdings Ltd", "priority": "normal", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "kind": "question", "dueDate": "2026-09-01" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPractitionerQueriesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPractitionerQueriesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/queries/{id}/answer": { "post": { "tags": [ "Accountant workspace" ], "summary": "Answer a query.", "operationId": "postApiPractitionerQueriesByIdAnswer", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string" } } }, "example": { "answer": "Attached — the September statement." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPractitionerQueriesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPractitionerQueriesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/queries/{id}/resolve": { "post": { "tags": [ "Accountant workspace" ], "summary": "Close a query.", "operationId": "postApiPractitionerQueriesByIdResolve", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPractitionerQueriesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPractitionerQueriesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/adjusting-journals": { "get": { "tags": [ "Accountant workspace" ], "summary": "Adjusting journals waiting on the client's review.", "operationId": "getApiPractitionerAdjustingJournals", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "journals": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiLedgerJournalsResponse" } }, "totalValue": { "type": "number" }, "count": { "type": "integer" } } }, "example": { "journals": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "journalNumber": "INV-0001", "journalDate": "2026-09-01", "sourceType": "invoice", "sourceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "reference": "INV-0001", "memo": "text", "status": "sent", "totalDebit": 10005.0, "totalCredit": 10005.0, "reversedBy": "text", "reverses": "text", "lines": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "accountCode": "CT-001", "accountName": "Karoo Fresh Holdings Ltd", "description": "Consulting services — August 2026", "debit": 1.0, "credit": 1.0, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "editable": false } ], "totalValue": 10005.0, "count": 3 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/session": { "post": { "tags": [ "Accountant workspace" ], "summary": "Open a client's books. Returns a short-lived access-only token scoped to that tenant; the client's own live link is the authority, so no permission in the practice's tenant is read.", "operationId": "postApiPractitionerClientsByIdSession", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string" }, "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "expiresInMinutes": { "type": "integer" }, "notice": { "type": "string" }, "placedByPractice": { "type": "boolean" } } }, "example": { "accessToken": "", "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Karoo Fresh Holdings Ltd", "expiresInMinutes": 1, "notice": "This run includes a catch-up deduction; the year-to-date total is correct.", "placedByPractice": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/billing": { "post": { "tags": [ "Accountant workspace" ], "summary": "Take over a client's subscription, or hand it back. Requires roles:edit.", "operationId": "postApiPractitionerClientsByIdBilling", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientTenantId": { "type": "string" }, "payer": { "type": "string" }, "clientNotice": { "type": "string" }, "chargedCentsMonthly": { "type": "integer" }, "proratedCentsNow": { "type": "integer" } } }, "example": { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "payer": "firm", "clientNotice": "This run includes a catch-up deduction; the year-to-date total is correct.", "chargedCentsMonthly": 49900, "proratedCentsNow": 49900 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/bulk-run": { "post": { "tags": [ "Accountant workspace" ], "summary": "Run one named action for up to 100 clients at once: vat201-check (what to look at before the VAT201 is filed), vat201-draft (prepare the VAT201 draft, never filed) or emp201-check (last month's EMP201 and what stops it being filed). Each client is entered through the same gate a visit uses and held to its own role and plan, so a client that refuses is refused alone, in its own words, and the others are run. Answers one outcome per client, in the order asked. Requires the Practice tier and roles:edit.", "operationId": "postApiPractitionerBulkRun", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPractitionerBulkRunResponse" }, "example": { "action": "vat201-check", "actionTitle": "Check the VAT201 before filing", "summary": "1 client: 1 done.", "outcomes": [ { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Karoo Fresh Holdings Ltd", "status": "done", "message": "VAT201 for 1 Oct 2026 to 31 Oct 2026: nothing to flag before filing." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/report-templates": { "get": { "tags": [ "Accountant workspace" ], "summary": "The practice's report templates, newest first: each a name and the checks (bulk-run actions) it runs, in order. promise is the one sentence that states what applying one does. Requires the Practice tier and roles:view.", "operationId": "getApiPractitionerReportTemplates", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerReportTemplatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerReportTemplatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Accountant workspace" ], "summary": "Keep a named set of checks (vat201-check, vat201-draft, emp201-check), each at most once, in the order given. Refused when the name is blank, over 60 characters or already used, when no check or an unknown or repeated one is chosen, or past 50 templates. Requires the Practice tier and roles:edit.", "operationId": "postApiPractitionerReportTemplates", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerReportTemplatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerReportTemplatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/report-templates/{id}/apply": { "post": { "tags": [ "Accountant workspace" ], "summary": "Apply a template to up to 100 clients: each check in it runs in order as bulk-run runs it (the same gate into each client, the client's own role and plan, one outcome per client), and the answer carries one run per check. Never files anything. Requires the Practice tier and roles:edit.", "operationId": "postApiPractitionerReportTemplatesByIdApply", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "templateName": { "type": "string" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiPractitionerBulkRunResponse" } } } }, "example": { "templateName": "Month end", "runs": [ { "action": "vat201-check", "actionTitle": "Check the VAT201 before filing", "summary": "1 client: 1 done.", "outcomes": [ { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Karoo Fresh Holdings Ltd", "status": "done", "message": "VAT201 for 1 Oct 2026 to 31 Oct 2026: nothing to flag before filing." } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/report-templates/{id}": { "delete": { "tags": [ "Accountant workspace" ], "summary": "Retire one of the practice's report templates. Nothing it already ran is touched. Requires the Practice tier and roles:edit.", "operationId": "deleteApiPractitionerReportTemplatesById", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerReportTemplatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerReportTemplatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/addons": { "get": { "tags": [ "Accountant workspace" ], "summary": "What this practice can turn on for one client, and what it costs the practice. Requires roles:view.", "operationId": "getApiPractitionerClientsByIdAddons", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "planId": { "type": "string" }, "planDisplayName": { "type": "string" }, "payer": { "type": "string" }, "blocker": { "type": "string" }, "held": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdAddonsResponseHeldItem" } }, "available": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdAddonsResponseHeldItem" } }, "addonCentsMonthly": { "type": "integer" } } }, "example": { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Karoo Fresh Holdings Ltd", "planId": "business", "planDisplayName": "Karoo Fresh Holdings Ltd", "payer": "firm", "blocker": "text", "held": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "displayName": "Karoo Fresh Holdings Ltd", "blurb": "Budget deferred to the next financial year.", "unitPriceMonthly": 2900.0, "quantity": 3, "monthlyPrice": 10005.0, "seatsPerUnit": 1, "unlocks": [ "text" ], "maxQuantity": 1, "unitLabel": "Karoo Fresh Holdings Ltd", "requiresNote": "Budget deferred to the next financial year.", "proRataCents": 49900, "proRataNote": "Budget deferred to the next financial year.", "pendingOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "pendingCheckoutUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "pendingAmountCents": 49900 } ], "available": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "displayName": "Karoo Fresh Holdings Ltd", "blurb": "Budget deferred to the next financial year.", "unitPriceMonthly": 2900.0, "quantity": 3, "monthlyPrice": 10005.0, "seatsPerUnit": 1, "unlocks": [ "text" ], "maxQuantity": 1, "unitLabel": "Karoo Fresh Holdings Ltd", "requiresNote": "Budget deferred to the next financial year.", "proRataCents": 49900, "proRataNote": "Budget deferred to the next financial year.", "pendingOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "pendingCheckoutUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "pendingAmountCents": 49900 } ], "addonCentsMonthly": 49900 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Accountant workspace" ], "summary": "The practice agreeing to an add-on for a client it pays for. Granted at once and charged on the practice's next consolidated cycle. Requires roles:edit.", "operationId": "postApiPractitionerClientsByIdAddons", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPractitionerClientsByIdAddonsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPractitionerClientsByIdAddonsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/addons/{addonId}": { "delete": { "tags": [ "Accountant workspace" ], "summary": "The practice taking an add-on off a client, and off its own next bill. Requires roles:edit.", "operationId": "deleteApiPractitionerClientsByIdAddonsByAddonId", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "addonId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPractitionerClientsByIdAddonsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPractitionerClientsByIdAddonsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/tax-references": { "get": { "tags": [ "Accountant workspace" ], "summary": "The SARS references on the holding company of a client the firm PLACED — VAT number and category, income tax, PAYE, UIF and SDL. A client that runs its own account answers 409 with the sentence telling the firm to ask the client to add them under Settings → Company. Requires roles:view.", "operationId": "getApiPractitionerClientsByIdTaxReferences", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdTaxReferencesResponse" }, "example": { "vatNumber": "4123456789", "vatCategory": "B", "taxNumber": "9123456789", "payeNumber": "7123456789", "uifNumber": "U123456789", "sdlNumber": "L123456789" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Accountant workspace" ], "summary": "Set a placed client's tax references, judged by the company profile's own rules. Null keeps a reference, blank clears it. Audited in the firm's trail and the client's. Refused (409) for a client that runs its own account. Requires roles:edit.", "operationId": "putApiPractitionerClientsByIdTaxReferences", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdTaxReferencesResponse" }, "example": { "vatNumber": "4123456789", "vatCategory": "B", "taxNumber": "9123456789", "payeNumber": "7123456789", "uifNumber": "U123456789", "sdlNumber": "L123456789" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/visit/filing-profile": { "get": { "tags": [ "Accountant workspace" ], "summary": "From a books visit: the visited company's VAT category and financial year end, the two settings that set when its returns are due. Answers 403 to anyone who is not a practice's visit. Requires sars:view.", "operationId": "getApiPractitionerVisitFilingProfile", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerVisitFilingProfileResponse" }, "example": { "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyName": "Sibanda Plumbing", "vatCategory": "B", "fiscalYearEndMonth": 2, "fiscalYearEndName": "February" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Accountant workspace" ], "summary": "From a books visit: correct the visited company's VAT category (A to F, or NONE), its financial year end (1 to 12), or both. Null leaves a setting alone; a blank category clears it. The numbers (VAT, PAYE, UIF, SDL, income tax) are not changed here. Judged by the rules Settings → Company uses, written to the same columns, and audited in the client's trail at warning with what changed and from what. Answers 403 to anyone who is not a practice's visit. Requires sars:approve.", "operationId": "putApiPractitionerVisitFilingProfile", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerVisitFilingProfileResponse" }, "example": { "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyName": "Sibanda Plumbing", "vatCategory": "B", "fiscalYearEndMonth": 6, "fiscalYearEndName": "June" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/fields": { "get": { "tags": [ "Accountant workspace" ], "summary": "The practice's own fields on one client — definitions and this client's answers in one call. The client is never shown these. Requires roles:view.", "operationId": "getApiPractitionerClientsByIdFields", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdFieldsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerClientsByIdFieldsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Accountant workspace" ], "summary": "Define a new field for the whole practice. It appears on every client, empty. Requires roles:edit.", "operationId": "postApiPractitionerClientsByIdFields", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdFieldsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerClientsByIdFieldsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/fields/{fieldId}": { "put": { "tags": [ "Accountant workspace" ], "summary": "Set or clear this client's answer. A blank value clears it and is not an error. Requires roles:edit.", "operationId": "putApiPractitionerClientsByIdFieldsByFieldId", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdFieldsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerClientsByIdFieldsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Accountant workspace" ], "summary": "Retire the field. Soft — it leaves the panel and every client's answer is kept. Requires roles:edit.", "operationId": "deleteApiPractitionerClientsByIdFieldsByFieldId", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdFieldsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerClientsByIdFieldsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/fields/{fieldId}/name": { "put": { "tags": [ "Accountant workspace" ], "summary": "Rename the field for the whole practice, keeping every client's answer. Requires roles:edit.", "operationId": "putApiPractitionerClientsByIdFieldsByFieldIdName", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdFieldsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerClientsByIdFieldsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/staff": { "get": { "tags": [ "Accountant workspace" ], "summary": "Who at the practice is on one client, who else could be, and the sentence the client is shown about it. Requires roles:view.", "operationId": "getApiPractitionerClientsByIdStaff", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdStaffResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerClientsByIdStaffResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Accountant workspace" ], "summary": "Assign a colleague at the practice to a client. The person the client invited by name already holds the grant and is refused. Requires roles:edit.", "operationId": "postApiPractitionerClientsByIdStaff", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdStaffResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerClientsByIdStaffResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/staff/{userId}": { "delete": { "tags": [ "Accountant workspace" ], "summary": "Take a colleague off a client. The person the client invited cannot be removed here — only the client can. Requires roles:edit.", "operationId": "deleteApiPractitionerClientsByIdStaffByUserId", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerClientsByIdStaffResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerClientsByIdStaffResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/time": { "get": { "tags": [ "Accountant workspace" ], "summary": "The firm's time across its whole client book, with what is unbilled per client. These are Time Tracking hours logged on Workflows cards that name a client — no separate timesheet. Money is in CENTS. Requires roles:view.", "operationId": "getApiPractitionerTime", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string" }, "nonBillableNote": { "type": "string" }, "unbilledCents": { "type": "integer" }, "notice": { "type": "null" }, "clients": { "type": "array", "items": { "type": "object", "properties": { "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "hours": { "type": "number" }, "nonBillableHours": { "type": "number" }, "unbilledHours": { "type": "number" }, "unbilledCents": { "type": "integer" }, "billedCents": { "type": "integer" }, "lastWorkedOn": { "type": "string", "format": "date" } } } } } }, "example": { "summary": "R 3 325.00 unbilled across 2 clients", "nonBillableNote": "0.75 hours are marked non-billable", "unbilledCents": 332500, "notice": null, "clients": [ { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Acme Trading (Pty) Ltd", "hours": 2.75, "nonBillableHours": 0.75, "unbilledHours": 2.0, "unbilledCents": 190000, "billedCents": 0, "lastWorkedOn": "2026-09-19" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/engagements": { "get": { "tags": [ "Accountant workspace" ], "summary": "What every client has agreed to, and for what fees. A letter is a quote on the contact that represents the client, so it is sent, signed and filed by the ordinary Invoicing and customer-portal path. Money is in CENTS. Requires roles:view.", "operationId": "getApiPractitionerEngagements", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string" }, "notice": { "type": "null" }, "clients": { "type": "array", "items": { "type": "object", "properties": { "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "documentId": { "type": "string" }, "documentNumber": { "type": "string" }, "status": { "type": "string" }, "statusWord": { "type": "string" }, "feeCents": { "type": "integer" }, "issuedOn": { "type": "string", "format": "date" }, "decidedOn": { "type": "string", "format": "date" }, "signedByName": { "type": "string" }, "declineReason": { "type": "null" }, "services": { "type": "array", "items": { "type": "string" } } } } }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "suggestedFee": { "type": "number" }, "scope": { "type": "string" } } } } } }, "example": { "summary": "1 of 2 clients have signed · 1 waiting on the client", "notice": null, "clients": [ { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Acme Trading (Pty) Ltd", "documentId": "6c2d51ae-90b7-4c33-8a52-7d1f4e0b93c5", "documentNumber": "QUO-2026-014", "status": "accepted", "statusWord": "Signed", "feeCents": 1955000, "issuedOn": "2026-09-19", "decidedOn": "2026-09-21", "signedByName": "Thandi Nkosi", "declineReason": null, "services": [ "Annual financial statements", "Company income tax return (ITR14)" ] } ], "services": [ { "id": "afs", "name": "Annual financial statements", "suggestedFee": 12500.0, "scope": "We compile your annual financial statements for each financial year from the records you keep in Ledgr, and we discuss them with you before they are signed." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/engagement/schedules": { "post": { "tags": [ "Accountant workspace" ], "summary": "Set up the client's ACCEPTED engagement letter's monthly fee lines (those that say per month) as recurring invoices in the practice's own invoicing: monthly, from the first of next month, each cycle left as a draft. Idempotent - a line already set up is found, not made again; the annual and once-off lines are left alone. Refused when the letter is not accepted or has no monthly fee. Answers what was done and the whole engagement view again. Requires invoices:create.", "operationId": "postApiPractitionerClientsByIdEngagementSchedules", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "notice": { "type": "string" }, "created": { "type": "integer" }, "alreadyThere": { "type": "integer" }, "view": { "type": "object", "properties": { "clients": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "string" }, "services": { "type": "array", "items": { "type": "object" } } } } } }, "example": { "notice": "Set up a recurring invoice. Find it under Invoicing, Recurring.", "created": 1, "alreadyThere": 0, "view": { "clients": [], "summary": "No clients to engage yet", "services": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/engagement": { "post": { "tags": [ "Accountant workspace" ], "summary": "Write one client's engagement letter from the chosen services, filled in with their name and the fees. Leaves it a DRAFT: sending it is POST /api/invoices/{id}/send, and the client signs by typing their name on the portal link. Refused while an unanswered letter is already out. Requires roles:edit.", "operationId": "postApiPractitionerClientsByIdEngagement", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string" }, "clients": { "type": "array", "items": { "type": "object" } } } }, "example": { "summary": "1 of 2 clients have signed · 1 waiting on the client", "clients": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/jobs": { "get": { "tags": [ "Accountant workspace" ], "summary": "What is outstanding across the whole client book, soonest due first. These are Workflows cards that name a client, not a separate job system. One page of 200 from offset; total, summary and overdueNote count the whole queue, and pageNote says which part this is. Requires roles:view.", "operationId": "getApiPractitionerJobs", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "offset", "in": "query", "required": false, "description": "How many rows to skip. Use with `limit` to page. A paged response reports `total`, which is the number of rows matching the filter rather than the number returned.", "schema": { "type": "integer" }, "example": "0" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string" }, "overdueNote": { "type": "string" }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string" }, "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "title": { "type": "string" }, "boardId": { "type": "string" }, "boardName": { "type": "string" }, "columnName": { "type": "string" }, "stage": { "type": "string" }, "priority": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "assigneeName": { "type": "string" } } } }, "boards": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPractitionerJobsResponseBoardsItem" } } } }, "example": { "summary": "12 open across 2 clients", "overdueNote": "3 are past their due date", "jobs": [ { "itemId": "8d21b6e0-77c4-4a15-9f30-1b5e9c2a7d64", "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Acme Trading (Pty) Ltd", "title": "EMP201 · Sept 2026", "boardId": "b41f0c93-2ad8-4e77-8c16-5f9e3d0a2b18", "boardName": "Compliance", "columnName": "In progress", "stage": "in_progress", "priority": "high", "dueDate": "2026-10-07", "overdue": false, "assigneeName": "Ayesha Patel" } ], "boards": [ { "boardId": "b41f0c93-2ad8-4e77-8c16-5f9e3d0a2b18", "name": "Compliance" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/franchise/links": { "get": { "tags": [ "Accountant workspace" ], "summary": "The franchisors this business lets read its reports, and invitations still waiting. explains says what a franchisor can and cannot see. Requires roles:view.", "operationId": "getApiFranchiseLinks", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "franchisorEmail": { "type": "string" }, "franchisorName": { "type": "string" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "invitedAt": { "type": "string" }, "acceptedAt": { "type": "string" } } } }, "explains": { "type": "string" } } }, "example": { "links": [ { "id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "franchisorEmail": "finance@kotaking.example", "franchisorName": "Head office", "status": "active", "statusLabel": "Reading your reports", "invitedAt": "2026-10-01T08:00:00Z", "acceptedAt": "2026-10-01T09:12:00Z" } ], "explains": "Your franchisor sees your income statement for any period they choose, read from your books when they ask. They cannot open your books, change anything, or see a single transaction, and nothing of yours is copied into their books. Remove their access here at any time." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Accountant workspace" ], "summary": "Let a franchisor read this business's income statement: an invitation to their email, which they accept from their own Ledgr business. Read-only; it opens no session in your books and copies nothing into theirs. Requires roles:create.", "operationId": "postApiFranchiseLinks", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } } }, "example": { "email": "finance@kotaking.example", "name": "Head office" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "franchisorEmail": { "type": "string" }, "franchisorName": { "type": "string" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "invitedAt": { "type": "string" } } }, "example": { "id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "franchisorEmail": "finance@kotaking.example", "franchisorName": "Head office", "status": "invited", "statusLabel": "Invited — waiting for them to accept", "invitedAt": "2026-10-01T08:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/franchise/links/{id}": { "delete": { "tags": [ "Accountant workspace" ], "summary": "Remove a franchisor's access at once; their next read is refused. Only the business that granted it can remove it. Requires roles:delete.", "operationId": "deleteApiFranchiseLinksById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/franchise/units": { "get": { "tags": [ "Accountant workspace" ], "summary": "The franchisor's side: the franchisees sharing their reports with this business, and invitations sent to your email to accept. Requires reports:view.", "operationId": "getApiFranchiseUnits", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "units": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiFranchiseUnitsResponseUnitsItem" } }, "invitations": { "type": "array", "items": { "type": "object" } } } }, "example": { "units": [ { "linkId": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "franchiseeName": "Kota King Soweto", "status": "active", "invitedAt": "2026-10-01T08:00:00Z", "acceptedAt": "2026-10-01T09:12:00Z" } ], "invitations": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/franchise/units/{id}/accept": { "post": { "tags": [ "Accountant workspace" ], "summary": "Accept a franchisee's invitation sent to your own email. Requires reports:view.", "operationId": "postApiFranchiseUnitsByIdAccept", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiFranchiseUnitsResponseUnitsItem" }, "example": { "linkId": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "franchiseeName": "Kota King Soweto", "status": "active", "invitedAt": "2026-10-01T08:00:00Z", "acceptedAt": "2026-10-01T09:12:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/franchise/units/{id}/report": { "get": { "tags": [ "Accountant workspace" ], "summary": "One franchisee's income statement for the period, one per company it keeps books for, read from its own ledger when you ask. Nothing is written into your books; the read is recorded in the franchisee's audit log. 404 once the franchisee removes your access. Requires reports:view.", "operationId": "getApiFranchiseUnitsByIdReport", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "linkId": { "type": "string" }, "franchiseeName": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "companyId": { "type": "string" }, "companyName": { "type": "string" }, "statement": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "revenue": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiFranchiseUnitsByIdReportResponseCompaniesItemStatementRevenueItem" } }, "costOfSales": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiFranchiseUnitsByIdReportResponseCompaniesItemStatementRevenueItem" } }, "operatingExpenses": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiFranchiseUnitsByIdReportResponseCompaniesItemStatementRevenueItem" } }, "otherIncome": { "type": "array", "items": { "type": "object" } }, "tax": { "type": "number" } } } } } }, "readOnly": { "type": "string" } } }, "example": { "linkId": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "franchiseeName": "Kota King Soweto", "from": "2026-09-01", "to": "2026-09-30", "companies": [ { "companyId": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b", "companyName": "Kota King Soweto (Pty) Ltd", "statement": { "periodLabel": "1 September 2026 – 30 September 2026", "revenue": [ { "name": "Sales", "amount": 184500.0, "accountId": "4f1c2b3a-1d2e-4c5b-8a9f-0e1d2c3b4a59" } ], "costOfSales": [ { "name": "Cost of sales", "amount": 92250.0, "accountId": "5a2b3c4d-5e6f-4a1b-9c8d-7e6f5a4b3c2d" } ], "operatingExpenses": [ { "name": "Rent", "amount": 28000.0, "accountId": "6b3c4d5e-6f7a-4b2c-8d9e-0f1a2b3c4d5e" } ], "otherIncome": [], "tax": 0.0 } } ], "readOnly": "Read from the franchisee's own books when you asked. It is not in your books and does not change them." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/jobs": { "post": { "tags": [ "Accountant workspace" ], "summary": "Raise work against one client on one of the practice's own boards. Raising the same title twice names the existing card instead of creating a second one. Requires roles:edit.", "operationId": "postApiPractitionerClientsByIdJobs", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string" }, "overdueNote": { "type": "null" }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string" }, "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "title": { "type": "string" }, "boardId": { "type": "string" }, "boardName": { "type": "string" }, "columnName": { "type": "string" }, "stage": { "type": "string" }, "priority": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "assigneeName": { "type": "null" } } } }, "boards": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPractitionerJobsResponseBoardsItem" } }, "notice": { "type": "string" } } }, "example": { "summary": "1 open for one client", "overdueNote": null, "jobs": [ { "itemId": "8d21b6e0-77c4-4a15-9f30-1b5e9c2a7d64", "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Acme Trading (Pty) Ltd", "title": "EMP201 · Sept 2026", "boardId": "b41f0c93-2ad8-4e77-8c16-5f9e3d0a2b18", "boardName": "Compliance", "columnName": "To do", "stage": "todo", "priority": "high", "dueDate": "2026-10-07", "overdue": false, "assigneeName": null } ], "boards": [ { "boardId": "b41f0c93-2ad8-4e77-8c16-5f9e3d0a2b18", "name": "Compliance" } ], "notice": "\"EMP201 · Sept 2026\" is already on Compliance." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/billing": { "get": { "tags": [ "Accountant workspace" ], "summary": "The practice's consolidated bill — one line per client it pays for, on one monthly charge.", "operationId": "getApiPractitionerBilling", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "planId": { "type": "string" }, "planDisplayName": { "type": "string" }, "listCentsMonthly": { "type": "integer" }, "chargedCentsMonthly": { "type": "integer" }, "addons": { "type": "array", "items": { "type": "object", "properties": { "addonId": { "type": "string" }, "addonName": { "type": "string" }, "quantity": { "type": "integer" }, "centsMonthly": { "type": "integer" } } } }, "totalCentsMonthly": { "type": "integer" } } } }, "totalCentsMonthly": { "type": "integer" }, "nextChargeOn": { "type": "string", "format": "date" }, "currentPeriodEnd": { "type": "string", "format": "date" }, "status": { "type": "string" }, "summary": { "type": "string" } } }, "example": { "lines": [ { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Karoo Fresh Holdings Ltd", "planId": "business", "planDisplayName": "Business", "listCentsMonthly": 49900, "chargedCentsMonthly": 49900, "addons": [ { "addonId": "logistics", "addonName": "Logistics & Fleet", "quantity": 1, "centsMonthly": 39900 } ], "totalCentsMonthly": 89800 } ], "totalCentsMonthly": 89800, "nextChargeOn": "2026-09-01", "currentPeriodEnd": "2026-09-30", "status": "active", "summary": "Consulting services — August 2026" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/payouts/statement": { "get": { "tags": [ "Accountant workspace" ], "summary": "The practice's payout statement for a period, as a PDF: each payout accrued in it — the client, the plan and term, what Ledgr collected, the rung's rate and the payout — with reversals after a client's plan change on their own lines, and what is still owed. Defaults to last calendar month.", "operationId": "getApiPractitionerPayoutsStatement", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-31" } ], "responses": { "200": { "description": "A PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/payouts": { "get": { "tags": [ "Accountant workspace" ], "summary": "This firm's own payout ledger: lifetime earned, lifetime paid, and what is still owed.", "operationId": "getApiPractitionerPayouts", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "earnedCentsLifetime": { "type": "integer" }, "paidCentsLifetime": { "type": "integer" }, "outstandingCents": { "type": "integer" } } }, "example": { "earnedCentsLifetime": 49900, "paidCentsLifetime": 49900, "outstandingCents": 49900 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/payout-bank-details": { "get": { "tags": [ "Accountant workspace" ], "summary": "The account Ledgr pays this firm's accrued payout into. The account number comes back masked.", "operationId": "getApiPractitionerPayoutBankDetails", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerPayoutBankDetailsResponse" }, "example": { "configured": false, "bankName": "FNB", "accountHolder": "text", "accountNumberMasked": "62012345678", "branchCode": "250655" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Accountant workspace" ], "summary": "Set or replace where Ledgr pays this firm's payout. Decides which bank account receives real money, so it needs roles:edit.", "operationId": "putApiPractitionerPayoutBankDetails", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankName": { "type": "string" }, "accountHolder": { "type": "string" }, "accountNumber": { "type": "string" }, "branchCode": { "type": "string" } } }, "example": { "bankName": "FNB", "accountHolder": "Example Accounting Inc", "accountNumber": "62012345678", "branchCode": "250655" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerPayoutBankDetailsResponse" }, "example": { "configured": true, "bankName": "FNB", "accountHolder": "text", "accountNumberMasked": "62012345678", "branchCode": "250655" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/directory-listing": { "get": { "tags": [ "Accountant workspace" ], "summary": "This firm's entry in the public find-an-accountant directory, whether it is shown, and — when Ledgr has hidden it — why.", "operationId": "getApiPractitionerDirectoryListing", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerDirectoryListingResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerDirectoryListingResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Accountant workspace" ], "summary": "Set or replace this firm's directory listing, the opt-in included. Only a partner practice may hold one. Nothing is published until optedIn is true, and re-saving never clears a hide Ledgr applied.", "operationId": "putApiPractitionerDirectoryListing", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "optedIn": { "type": "boolean" }, "displayName": { "type": "string" }, "town": { "type": "string" }, "province": { "type": "string" }, "services": { "type": "array", "items": { "type": "string" } }, "contactEmail": { "type": "string" }, "website": { "type": "string" } } }, "example": { "optedIn": true, "displayName": "Mokoena & Associates", "town": "Polokwane", "province": "limpopo", "services": [ "tax", "vat", "payroll" ], "contactEmail": "hello@mokoena.example", "website": "https://mokoena.example" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerDirectoryListingResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerDirectoryListingResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/professional-registration": { "get": { "tags": [ "Accountant workspace" ], "summary": "This firm's professional-body registration, and what its payout rate is being held at until Ledgr has checked it.", "operationId": "getApiPractitionerProfessionalRegistration", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerProfessionalRegistrationResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerProfessionalRegistrationResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Accountant workspace" ], "summary": "Submit or correct this firm's body and membership number. A firm cannot verify itself — the only status this produces is submitted.", "operationId": "putApiPractitionerProfessionalRegistration", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "membershipNumber": { "type": "string" } } }, "example": { "body": "saica", "membershipNumber": "20012345" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerProfessionalRegistrationResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerProfessionalRegistrationResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/account-templates": { "get": { "tags": [ "Accountant workspace" ], "summary": "The firm's standard charts of accounts, each captured from one client and applicable to any other. `promise` is the single sentence that states what applying one does, so the console, the confirmation and any help page cannot disagree.", "operationId": "getApiPractitionerAccountTemplates", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerAccountTemplatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerAccountTemplatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Accountant workspace" ], "summary": "Keep one client's chart of accounts as a named template. Refused when the client has nothing beyond the standard chart, when the name is already in use, or past the ceilings (100 templates, 500 accounts) — never silently truncated.", "operationId": "postApiPractitionerAccountTemplates", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerAccountTemplatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerAccountTemplatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/account-templates/{templateId}/apply/{clientId}": { "post": { "tags": [ "Accountant workspace" ], "summary": "Install a template into a client's chart, into its holding company or, with `?companyId=`, into one of the client's other companies (another client's company is not found). It can only ADD: a code the client already holds — live OR deleted — is skipped and reported by name, never renamed, re-parented, re-typed or revived. `skipped` is the safety rule working, not a partial failure.", "operationId": "postApiPractitionerAccountTemplatesByTemplateIdApplyByClientId", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "6b7f6d0e-3a52-4c1e-8a54-0c4f5f6a7b01" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "reason": { "type": "string" } } } }, "notice": { "type": "string" } } }, "example": { "added": [ "6410", "6420" ], "skipped": [ { "code": "6400", "name": "Kitchen costs", "reason": "the client already has this code" } ], "notice": "Added 2 accounts · left 1 account alone because the client already has those codes." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/companies": { "get": { "tags": [ "Accountant workspace" ], "summary": "The companies of a linked client, the holding company first, so a template can be installed into the one that needs it (`POST .../apply/{clientId}?companyId=`). Requires roles:view.", "operationId": "getApiPractitionerClientsByIdCompanies", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiInventorySuppliersResponseItem" } } } }, "example": { "companies": [ { "id": "6b7f6d0e-3a52-4c1e-8a54-0c4f5f6a7b01", "name": "Naidoo Eatery" }, { "id": "9d1c2e44-7b10-4f6a-b2a7-5a3c8d0e1f22", "name": "Naidoo Catering" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/account-templates/{templateId}": { "delete": { "tags": [ "Accountant workspace" ], "summary": "Retire one of the firm's templates. Nothing already applied to a client is touched — an applied template leaves accounts, not a link.", "operationId": "deleteApiPractitionerAccountTemplatesByTemplateId", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerAccountTemplatesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerAccountTemplatesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/clients/{id}/invoice": { "post": { "tags": [ "Accountant workspace" ], "summary": "Raise the firm's own invoice to one client from its approved, unbilled hours, grouped by the work and the rate each hour was captured at. Every entry billed is stamped with the invoice in the same transaction, so a second call finds nothing to bill rather than billing twice.", "operationId": "postApiPractitionerClientsByIdInvoice", "description": "Requires the `practice:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string" }, "notice": { "type": "string" }, "unbilledCents": { "type": "integer" }, "clients": { "type": "array", "items": { "type": "object", "properties": { "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "hours": { "type": "number" }, "unbilledHours": { "type": "number" }, "unbilledCents": { "type": "integer" }, "readyToBillHours": { "type": "number" }, "readyToBillCents": { "type": "integer" }, "awaitingApprovalHours": { "type": "number" }, "awaitingApprovalCents": { "type": "integer" }, "billedCents": { "type": "integer" }, "lastWorkedOn": { "type": "string", "format": "date" } } } } } }, "example": { "summary": "R 1 425.00 unbilled across 1 client", "notice": "Invoice INV-2026-014 raised for 2 hours, R 1 900.00. Those entries are now billed.", "unbilledCents": 142500, "clients": [ { "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Naidoo Logistics Prof", "hours": 1.5, "unbilledHours": 1.5, "unbilledCents": 142500, "readyToBillHours": 1.5, "readyToBillCents": 142500, "awaitingApprovalHours": 0.0, "awaitingApprovalCents": 0, "billedCents": 0, "lastWorkedOn": "2026-09-01" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/queries/{id}/files": { "post": { "tags": [ "Accountant workspace" ], "summary": "Answer a document request by sending a file. Refused on a QUESTION — a firm that asked \"which account is this?\" and got back a PDF has an answer nobody will read — and the remedy is named rather than implied.", "operationId": "postApiPractitionerQueriesByIdFiles", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "filename", "in": "query", "required": false, "description": "The name to give the downloaded file.", "schema": { "type": "string" }, "example": "SignedPO-4417.pdf" }, { "name": "caption", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Serial%20plate%20before%20fitting" }, { "name": "contentType", "in": "query", "required": false, "schema": { "type": "string" }, "example": "application%2Fpdf" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerQueriesByIdFilesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerQueriesByIdFilesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Accountant workspace" ], "summary": "One request and everything sent against it, each file with a signed, time-limited URL. A request is ANSWERED by a file arriving, which is why `statusWord` and `fileCount` are served rather than recomputed by either screen.", "operationId": "getApiPractitionerQueriesByIdFiles", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPractitionerQueriesByIdFilesResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiPractitionerQueriesByIdFilesResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/practitioner/document-requests": { "get": { "tags": [ "Accountant workspace" ], "summary": "The firm's chase list: every document request its own people raised, across the whole client book, with what has arrived. Separate from /api/practitioner/queries because a request lives in the CLIENT's tenant — that endpoint answers a firm with its own queries. Scoped by the ASKER, not by the link, so two firms serving one client never see each other's requests.", "operationId": "getApiPractitionerDocumentRequests", "description": "Requires the `practice:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "practice:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string" }, "notice": { "type": "null" }, "requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "clientTenantId": { "type": "string" }, "clientName": { "type": "string" }, "question": { "type": "string" }, "dueDate": { "type": [ "string", "null" ] }, "fileCount": { "type": "integer" }, "statusWord": { "type": "string" }, "outstanding": { "type": "boolean" }, "overdue": { "type": "boolean" }, "askedByEmail": { "type": "string" }, "createdAt": { "type": "string" } } } } } }, "example": { "summary": "2 of 2 still open · 1 past the date", "notice": null, "requests": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Naidoo Logistics Prof", "question": "Please send the February bank statement.", "dueDate": "2026-09-10", "fileCount": 0, "statusWord": "Overdue", "outstanding": true, "overdue": false, "askedByEmail": "owner.prac@ledgraudit.test", "createdAt": "2026-09-01T09:15:00Z" }, { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientTenantId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "clientName": "Thabo Holdings Group", "question": "The vehicle finance agreement, please.", "dueDate": null, "fileCount": 1, "statusWord": "1 sent", "outstanding": true, "overdue": false, "askedByEmail": "owner.prac@ledgraudit.test", "createdAt": "2026-09-02T07:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/whatsapp/config": { "get": { "tags": [ "WhatsApp" ], "summary": "Whether WhatsApp is configured, and which templates are approved.", "operationId": "getApiWhatsappConfig", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "enabled": { "type": "boolean" }, "sending": { "type": "boolean" }, "reason": { "type": "string" } } }, "example": { "configured": false, "enabled": true, "sending": false, "reason": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "WhatsApp" ], "summary": "Set the tenant's WhatsApp configuration.", "operationId": "putApiWhatsappConfig", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "senderDisplayName": { "type": "string" } } }, "example": { "enabled": true, "senderDisplayName": "Your Business" } } } }, "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/whatsapp/receipt-senders": { "get": { "tags": [ "WhatsApp" ], "summary": "The phones you have linked to send receipts by WhatsApp, a code waiting to be sent, and Ledgr's number.", "operationId": "getApiWhatsappReceiptSenders", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ledgrNumber": { "type": "string" }, "onPlan": { "type": "boolean" }, "refusal": { "type": "null" }, "linked": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "numberEnding": { "type": "string" }, "linkedAt": { "type": "string" } } } }, "pending": { "type": "null" } } }, "example": { "ledgrNumber": "+27 87 000 0000", "onPlan": true, "refusal": null, "linked": [ { "id": "7d4f0c1e-2b8a-4f3e-9c55-0f7d2e1a6b90", "numberEnding": "4567", "linkedAt": "2026-10-12T10:15:00Z" } ], "pending": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "WhatsApp" ], "summary": "Start linking your phone: a code to send FROM it to Ledgr's number. The phone is linked when the code arrives.", "operationId": "postApiWhatsappReceiptSenders", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "ledgrNumber": { "type": "string" }, "expiresAt": { "type": "string" } } }, "example": { "code": "482913", "message": "LINK 482913", "ledgrNumber": "+27 87 000 0000", "expiresAt": "2026-10-12T10:45:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/whatsapp/receipt-senders/{id}": { "delete": { "tags": [ "WhatsApp" ], "summary": "Unlink one of your phones; what it sends afterwards is dropped.", "operationId": "deleteApiWhatsappReceiptSendersById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/whatsapp/messages": { "get": { "tags": [ "WhatsApp" ], "summary": "Messages sent and their delivery state.", "operationId": "getApiWhatsappMessages", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiWhatsappSendResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "to": "2026-09-30", "templateName": "Karoo Fresh Holdings Ltd", "status": "sent", "createdAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/whatsapp/messages/{id}": { "get": { "tags": [ "WhatsApp" ], "summary": "One message.", "operationId": "getApiWhatsappMessagesById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/whatsapp/send": { "post": { "tags": [ "WhatsApp" ], "summary": "Send a message against an approved template.", "operationId": "postApiWhatsappSend", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWhatsappSendRequest" }, "example": { "to": "2026-09-30", "templateName": "Karoo Fresh Holdings Ltd", "templateParams": { "1": "Karoo Fresh Holdings Ltd" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWhatsappSendResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "to": "2026-09-30", "templateName": "Karoo Fresh Holdings Ltd", "status": "sent", "createdAt": "2026-09-01T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/whatsapp/test": { "post": { "tags": [ "WhatsApp" ], "summary": "Send a test message to prove the configuration, rather than discovering it at the first real send.", "operationId": "postApiWhatsappTest", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiWhatsappSendRequest" }, "example": { "to": "2026-09-30", "templateName": "Karoo Fresh Holdings Ltd", "templateParams": { "1": "Karoo Fresh Holdings Ltd" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "to": { "type": "string", "format": "date" } } }, "example": { "status": "sent", "to": "2026-09-30" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/external/contacts/{contactId}/transactions": { "get": { "tags": [ "External ingest (API key)" ], "summary": "Billable events already posted for a contact. Scope transactions:read plus a key bound to that contact.", "operationId": "getExternalContactsByContactIdTransactions", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Return only rows in this state. Matched case-insensitively; a value that is not one of the statuses is REFUSED rather than ignored, because a filter that quietly answers with everything is the worst outcome.", "schema": { "type": "string" }, "example": "open" }, { "name": "from", "in": "query", "required": false, "description": "Start of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "End of the period, inclusive, as `YYYY-MM-DD`. An unparseable date is refused rather than defaulted.", "schema": { "type": "string", "format": "date" }, "example": "2027-02-28" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiContactsByContactIdTransactionsResponseItem" } }, "examples": { "default": { "$ref": "#/components/examples/GetApiContactsByContactIdTransactionsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "External ingest (API key)" ], "summary": "Post a billable event. Scope transactions:write plus a bound contact, set when the key is generated under Roles → API keys.", "operationId": "postExternalContactsByContactIdTransactions", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "occurredAt": { "type": "string", "format": "date" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "currency": { "type": "string" }, "vatRate": { "type": "number" }, "externalRef": { "type": "string" } } }, "example": { "occurredAt": "2026-08-14", "description": "1 200 API calls", "quantity": 1200.0, "unitPrice": 0.85, "currency": "ZAR", "vatRate": 15.0, "externalRef": "usage-2026-08-14-a1" } } } }, "responses": { "201": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/external/contacts/{contactId}/transactions/{id}": { "delete": { "tags": [ "External ingest (API key)" ], "summary": "Remove an event before it has been invoiced.", "operationId": "deleteExternalContactsByContactIdTransactionsById", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/external/leads": { "post": { "tags": [ "External ingest (API key)" ], "summary": "Web-to-lead. Scope crm:write. Made idempotent by the caller's own external_ref under a unique index — a website form that retries on a dropped response must not create the lead twice, because two reps then phone the customer.", "operationId": "postExternalLeads", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "companyName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "source": { "type": "string" }, "estimatedValue": { "type": "number" }, "notes": { "type": "string" }, "campaign": { "type": "string" }, "externalRef": { "type": "string" } } }, "example": { "name": "Sipho Dlamini", "companyName": "Dlamini Logistics", "email": "sipho@dlamini.example", "phone": "+27821234567", "source": "website", "estimatedValue": 10005.0, "notes": "Enquiry from the website contact form.", "campaign": "Spring promotion", "externalRef": "INV-0001" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "leadId": { "type": "string" }, "status": { "type": "string" } } }, "example": { "leadId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/channels": { "get": { "tags": [ "Inbound webhooks" ], "summary": "The company's connected online stores (market-platform T-P3.1): each store, the webhook address to paste into its notification settings, how many products matched it by SKU, how many orders became invoices, and every order it holds because Ledgr cannot fill it yet (an unknown SKU, no stock, another currency) with the reason. Credentials are never returned.", "operationId": "getApiChannels", "description": "Requires the `inventory:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "storeAddress": { "type": "string" }, "webhookUrl": { "type": "string" }, "productsMatched": { "type": "integer" }, "ordersTaken": { "type": "integer" }, "lastReconciledAt": { "type": "string" }, "stockLocationId": { "type": "null" }, "stockLocationName": { "type": "null" }, "payoutsNotTied": { "type": "integer" }, "waitingOrders": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string" }, "reason": { "type": "string" }, "receivedAt": { "type": "string" } } } }, "ledgrSetsPrices": { "type": "boolean" }, "historyFrom": { "type": "string", "format": "date" }, "historyDone": { "type": "boolean" }, "historyOrdersRead": { "type": "integer" } } } }, "example": [ { "id": "5d2b7c1e-9f43-4a8e-b6d0-3c1a2e4f5b67", "kind": "shopify", "label": "Shopify", "storeAddress": "umlazi-tees.myshopify.com", "webhookUrl": "https://app.ledgr.example/webhooks/shopify/5d2b7c1e-9f43-4a8e-b6d0-3c1a2e4f5b67", "productsMatched": 12, "ordersTaken": 48, "lastReconciledAt": "2026-10-11T02:00:04Z", "stockLocationId": null, "stockLocationName": null, "payoutsNotTied": 0, "waitingOrders": [ { "number": "#1003", "reason": "Order #1003 sells SKU MUG-02 (Enamel mug), which is no product in Ledgr. Give a product that SKU, or add it, and the order is taken.", "receivedAt": "2026-10-16T09:41:12Z" } ], "ledgrSetsPrices": false, "historyFrom": "2026-10-01", "historyDone": false, "historyOrdersRead": 250 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inbound webhooks" ], "summary": "Connect a store. Shopify is reached at its myshopify.com address only, with the custom app's Admin API access token and webhook signing secret; WooCommerce at the https address of the tenant's own site (it must resolve to a public address), with its consumer key (accessToken), consumer secret (accessSecret) and webhook secret. Takealot by the seller's account name and Marketplace API key alone (webhookSecret empty): it sends no webhooks and is read every few minutes by the channel-poll job; connecting it makes a 'Takealot warehouse' stock location for the stock Takealot holds. Every credential is held as a SecretBox envelope. The store is asked for its stock location before anything is saved, products are matched by SKU, and Ledgr's available stock (on hand less reserved) is sent at once. historyFrom (YYYY-MM-DD, default the first of this month; refused when after today or before the books are open — the opening balances or a closed month) is the day the store's past PAID orders are brought in from: the channel-poll job reads them a page per run up to the moment of connecting, through the same intake as a webhook (an order already taken is not taken twice; an unknown SKU is held), and the store's card reports historyFrom, historyDone and historyOrdersRead. Takealot's first poll starts at that day.", "operationId": "postApiChannels", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "storeAddress": { "type": "string" }, "accessToken": { "type": "string" }, "webhookSecret": { "type": "string" }, "accessSecret": { "type": "null" }, "ledgrSetsPrices": { "type": "boolean" }, "historyFrom": { "type": "string", "format": "date" } } }, "example": { "kind": "shopify", "storeAddress": "umlazi-tees.myshopify.com", "accessToken": "shpat_0123456789abcdef", "webhookSecret": "whsec_0123456789abcdef", "accessSecret": null, "ledgrSetsPrices": false, "historyFrom": "2026-10-01" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "storeAddress": { "type": "string" }, "webhookUrl": { "type": "string" }, "productsMatched": { "type": "integer" }, "ordersTaken": { "type": "integer" }, "lastReconciledAt": { "type": "string" }, "stockLocationId": { "type": "null" }, "stockLocationName": { "type": "null" }, "payoutsNotTied": { "type": "integer" }, "waitingOrders": { "type": "array", "items": { "type": "object" } }, "ledgrSetsPrices": { "type": "boolean" }, "historyFrom": { "type": "string", "format": "date" }, "historyDone": { "type": "boolean" }, "historyOrdersRead": { "type": "integer" } } }, "example": { "id": "5d2b7c1e-9f43-4a8e-b6d0-3c1a2e4f5b67", "kind": "shopify", "label": "Shopify", "storeAddress": "umlazi-tees.myshopify.com", "webhookUrl": "https://app.ledgr.example/webhooks/shopify/5d2b7c1e-9f43-4a8e-b6d0-3c1a2e4f5b67", "productsMatched": 12, "ordersTaken": 48, "lastReconciledAt": "2026-10-11T02:00:04Z", "stockLocationId": null, "stockLocationName": null, "payoutsNotTied": 0, "waitingOrders": [], "ledgrSetsPrices": false, "historyFrom": "2026-10-01", "historyDone": false, "historyOrdersRead": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/channels/{id}/take-waiting": { "post": { "tags": [ "Inbound webhooks" ], "summary": "Take this store's held orders now, where they can be filled — a product given the order's SKU, or the stock received. Each is booked once, exactly as if it had just arrived; what still cannot be filled stays held with its reason. The channel-poll job does the same every few minutes. Needs invoices:create.", "operationId": "postApiChannelsByIdTakeWaiting", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taken": { "type": "integer" }, "stillWaiting": { "type": "integer" } } }, "example": { "taken": 1, "stillWaiting": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/channels/{id}": { "patch": { "tags": [ "Inbound webhooks" ], "summary": "Change a connected store's settings. ledgrSetsPrices (off unless turned on, here or when connecting) lets Ledgr set the store's prices: each matched product's selling price, VAT included where the business charges it, is sent now and again whenever it changes in Ledgr, and the channel-poll job sends any change it missed. Shopify's variant price, WooCommerce's regular_price, Takealot's selling_price in whole rand. A store's own price is never read back into Ledgr. A field left out keeps its value. Needs the owner or an administrator.", "operationId": "patchApiChannelsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ledgrSetsPrices": { "type": "boolean" } } }, "example": { "ledgrSetsPrices": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "storeAddress": { "type": "string" }, "webhookUrl": { "type": "string" }, "productsMatched": { "type": "integer" }, "ordersTaken": { "type": "integer" }, "lastReconciledAt": { "type": "string" }, "stockLocationId": { "type": "null" }, "stockLocationName": { "type": "null" }, "payoutsNotTied": { "type": "integer" }, "waitingOrders": { "type": "array", "items": { "type": "object" } }, "ledgrSetsPrices": { "type": "boolean" } } }, "example": { "id": "5d2b7c1e-9f43-4a8e-b6d0-3c1a2e4f5b67", "kind": "shopify", "label": "Shopify", "storeAddress": "umlazi-tees.myshopify.com", "webhookUrl": "https://app.ledgr.example/webhooks/shopify/5d2b7c1e-9f43-4a8e-b6d0-3c1a2e4f5b67", "productsMatched": 12, "ordersTaken": 48, "lastReconciledAt": "2026-10-11T02:00:04Z", "stockLocationId": null, "stockLocationName": null, "payoutsNotTied": 0, "waitingOrders": [], "ledgrSetsPrices": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Inbound webhooks" ], "summary": "Disconnect a store. Its credentials are discarded; the invoices its orders raised stay.", "operationId": "deleteApiChannelsById", "description": "Requires the `inventory:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "inventory:write" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/developers/playground/spec.json": { "get": { "tags": [ "Operations & discovery" ], "summary": "This catalogue, as JSON, with each endpoint's module, plan and scope resolved. What the playground renders.", "operationId": "getDevelopersPlaygroundSpec.json", "security": [], "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/pos/journals": { "post": { "tags": [ "Point of sale" ], "summary": "Post a point-of-sale journal once. A replay of the same clientId answers the journal it made (200); the first post answers 201. Refused unless it balances, every account is in the chart, and a bank leg names a bank account (bank:). A sales journal's 2130 must also agree with the supplies it states at the VAT rate on its date, to a cent per till slip it summarises (supplies.receipts). A line may not name a control account a register owns (1310 Inventory, 1315, 1320, 1360, 1365, 1366, 2110, 2155-2157) or the pooled bank control 1350: the refusal names the account and the door that moves it. The goods a sales journal sold go in items [{productId, quantity, locationId?}]: they leave the stock batches at their cost (FIFO or average as the product is costed; a kit sells its parts; more than is on hand is refused before a unit moves), and the journal gains DR 5040 / CR 1310 for that cost, answered as costOfSalesCents. A replay of the same clientId relieves the stock once. Items on a journal that is not a sale, an untracked product, and a return of goods (use a credit note) are refused.", "operationId": "postApiPosJournals", "description": "Requires the `reports:write` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:write" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "kind": { "type": "string" }, "journalDate": { "type": "string", "format": "date" }, "reference": { "type": "string" }, "memo": { "type": "string" }, "locationRef": { "type": "string" }, "locationName": { "type": "string" }, "currency": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string" }, "debitCents": { "type": "integer" }, "creditCents": { "type": "integer" }, "description": { "type": "string" } } } }, "supplies": { "type": "object", "properties": { "standardRatedNetCents": { "type": "integer" }, "zeroRatedCents": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "quantity": { "type": "integer" }, "locationId": { "type": "null" } } } } } }, "example": { "clientId": "6f1d2c7a-3b4e-3c5d-9e8f-0a1b2c3d4e5f", "kind": "sales", "journalDate": "2026-10-01", "reference": "ruva:day:loc-main:2026-10-01:r1", "memo": "Daily sales — Main", "locationRef": "loc-main", "locationName": "Main", "currency": "ZAR", "lines": [ { "account": "1362", "debitCents": 34500, "creditCents": 0, "description": "Cash takings" }, { "account": "1355", "debitCents": 80000, "creditCents": 0, "description": "Card takings" }, { "account": "4010", "debitCents": 0, "creditCents": 99565, "description": "Sales" }, { "account": "2130", "debitCents": 0, "creditCents": 14935, "description": "Output VAT" } ], "supplies": { "standardRatedNetCents": 99565, "zeroRatedCents": 0 }, "items": [ { "productId": "9b2e5c1a-7d34-4f08-a6c1-3e5d8f0b2a47", "quantity": 2, "locationId": null } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPosJournalsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPosJournalsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/pos/journals/{clientId}": { "get": { "tags": [ "Point of sale" ], "summary": "A point-of-sale journal by the system's own id, with the VAT it carries.", "operationId": "getApiPosJournalsByClientId", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPosJournalsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiPosJournalsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/pos/accounts": { "get": { "tags": [ "Point of sale" ], "summary": "What a point-of-sale line may name: the company's active ledger accounts by code, and its open bank accounts as bank:. The pooled bank control (1350) and the controls a register owns (1310, 1315, 1320, 1360, 1365, 1366, 2110, 2155-2157) are not listed: a journal naming one is refused.", "operationId": "getApiPosAccounts", "description": "Requires the `reports:read` scope when called with an API key. A first-party token is limited by the user's role instead.", "x-ledgr-scope": [ "reports:read" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" } } } }, "example": [ { "ref": "bank:3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "code": "bank", "name": "Current" }, { "ref": "1355", "code": "1355", "name": "Card Settlement Clearing" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } } }