{ "openapi": "3.1.0", "info": { "title": "Ledgr API", "version": "v1", "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": "Billing & subscription" }, { "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": "Customer ordering portal pages" }, { "name": "Expenses & claims" }, { "name": "Purchasing & suppliers" }, { "name": "Banking & reconciliation" }, { "name": "General ledger" }, { "name": "Reports & analytics" }, { "name": "SARS returns" }, { "name": "Payroll" }, { "name": "Leave" }, { "name": "Employee self-service portal" }, { "name": "Inventory" }, { "name": "Job cards" }, { "name": "Service contracts" }, { "name": "Time tracking" }, { "name": "Workflows" }, { "name": "Bills of materials" }, { "name": "Material planning (MRP)" }, { "name": "Production & work orders" }, { "name": "Procurement" }, { "name": "Supplier portal API" }, { "name": "Supplier portal pages" }, { "name": "Supplier workspace, buyer side" }, { "name": "Logistics & fleet" }, { "name": "Driver app API" }, { "name": "Multi-company & consolidation" }, { "name": "Accountant workspace" }, { "name": "Migration & take-on" }, { "name": "Offline sync" }, { "name": "WhatsApp" }, { "name": "External ingest (API key)" }, { "name": "Inbound webhooks" }, { "name": "Platform administration" }, { "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 Settings → Roles → 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" } } }, "DeleteApiPushTokensResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "revoked": { "type": "integer" } } }, "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" } } }, "GetApiBillingSubscriptionResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "plan": { "type": "string" }, "planDisplayName": { "type": "string" }, "termMonths": { "type": "integer" }, "status": { "type": "string" }, "autoRenew": { "type": "boolean" }, "currentPeriodStart": { "type": "string", "format": "date" }, "currentPeriodEnd": { "type": "string", "format": "date" }, "nextRenewalOn": { "type": "string", "format": "date" }, "daysUntilRenewal": { "type": "integer" }, "renewalAmountCents": { "type": "integer" }, "pendingOrderId": { "type": "string" }, "pendingCheckoutUrl": { "type": "string" }, "summary": { "type": "string" }, "cancelsOn": { "type": "string", "format": "date" }, "cancellationNotice": { "type": "string" } } }, "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" } } }, "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 3 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 3 operations.", "type": "object", "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "reason": { "type": "string" } } }, "GetApiCompanyHierarchyByIdConsolidatedTrialBalanceResponseEliminationsExternalItem": { "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" } } }, "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" } } }, "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" } } }, "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" } } }, "GetApiCrmLeadsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiCrmLeadsResponseItemsItem" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "GetApiCrmLeadsResponseItemsItem": { "description": "Shared by 6 operations.", "type": "object", "properties": {} }, "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 4 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" } } }, "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 2 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" } } }, "GetApiExpensesCountResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "total": { "type": "integer" } } }, "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" } } }, "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" } } }, "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 9 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" } } }, "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" } }, "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 9 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 9 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" } } }, "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" } } }, "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/GetAuthSsoProvidersResponseItem" } }, "standard": { "type": "array", "items": { "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" }, "address": { "type": "string" }, "city": { "type": "string" }, "lineCount": { "type": "integer" }, "totalQty": { "type": "number" }, "total": { "type": "number" }, "currency": { "type": "string" } } }, "GetApiMeSsoIdentitiesResponseItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "provider": { "type": "string" }, "email": { "type": "string" }, "linkedAt": { "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 2 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" } } }, "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" }, "annualPaye": { "type": "number" }, "annualUif": { "type": "number" }, "annualSdl": { "type": "number" }, "annualEti": { "type": "number" }, "annualTotal": { "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" } } }, "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 2 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" } } }, "GetApiPayrollEtiResponseClaim": { "description": "Shared by 2 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 2 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" } } }, "GetApiPayrollIrp5ResponseItem": { "description": "Shared by 2 operations.", "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" }, "periodsInYear": { "type": "integer" }, "takeOnIncluded": { "type": "boolean" }, "takeOnGrossRemuneration": { "type": "number" }, "takeOnPaye": { "type": "number" }, "takeOnSourceLabel": { "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" } } }, "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 5 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" } } }, "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" } } }, "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" } } }, "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 3 operations.", "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "roleName": { "type": "string" }, "isSelf": { "type": "boolean" } } }, "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" } } }, "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" } } }, "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" } } }, "GetApiPushPreferencesResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "topics": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiPushPreferencesResponseTopicsItem" } } } }, "GetApiPushPreferencesResponseTopicsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "topic": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "allowedByBusiness": { "type": "boolean" }, "enabled": { "type": "boolean" } } }, "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" } } }, "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" }, "averageEmployees": { "type": "integer" }, "beneficialInterestHolders": { "type": "integer" }, "internallyCompiled": { "type": "boolean" }, "ownerManaged": { "type": "boolean" } } }, "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" } } }, "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 7 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" } } }, "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 5 operations.", "type": "object", "properties": { "title": { "type": "string" }, "note": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsDocumentsIrp6ResponseSectionsItemFieldsItem" } } } }, "GetApiSarsDocumentsIrp6ResponseSectionsItemFieldsItem": { "description": "Shared by 5 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" } } }, "GetApiSarsTransmissionsIsvResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "configured": { "type": "boolean" }, "missingConfiguration": { "type": "array", "items": { "type": "string" } }, "production": { "type": "boolean" }, "baseUrl": { "type": "string" }, "isvId": { "type": "string" }, "supportedTaxTypes": { "type": "array", "items": { "type": "string" } }, "certificateSubject": { "type": "string" }, "certificateExpiresAt": { "type": "string" }, "certificateDaysRemaining": { "type": "integer" }, "certificateExpired": { "type": "boolean" }, "summary": { "type": "string" } } }, "GetApiSarsTransmissionsResponseTransmissionsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "submissionId": { "type": "string" }, "taxType": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "channel": { "type": "string" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "testSubmission": { "type": "boolean" }, "sarsReference": { "type": "string" }, "sarsStatusRaw": { "type": "string" }, "lastError": { "type": "string" }, "attempts": { "type": "integer" }, "sentAt": { "type": "string" }, "acknowledgedAt": { "type": "string" }, "nextAttemptAt": { "type": "string" }, "envelopeFormat": { "type": "string" }, "envelopeBytes": { "type": "integer" }, "createdAt": { "type": "string" } } }, "GetApiSetupProgressResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "completedKeys": { "type": "array", "items": { "type": "string" } }, "markedKeys": { "type": "array", "items": { "type": "string" } }, "detectedKeys": { "type": "array", "items": { "type": "string" } }, "checklistHidden": { "type": "boolean" } } }, "GetApiStatutoryEffectiveResponse": { "type": "object", "properties": { "revision": { "type": "string" }, "taxYears": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiStatutoryEffectiveResponseTaxYearsItem" } }, "vatRates": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiStatutoryEffectiveResponseVatRatesItem" } }, "companyTaxRates": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiStatutoryEffectiveResponseCompanyTaxRatesItem" } }, "calendarDays": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiStatutoryEffectiveResponseCalendarDaysItem" } }, "filingDeadlines": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiStatutoryEffectiveResponseFilingDeadlinesItem" } }, "dividendsTaxRates": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiStatutoryEffectiveResponseDividendsTaxRatesItem" } }, "etiBands": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiStatutoryEffectiveResponseEtiBandsItem" } } } }, "GetApiStatutoryEffectiveResponseCalendarDaysItem": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "name": { "type": "string" }, "kind": { "type": "string" }, "source": { "type": "string" }, "publishedBy": { "type": "string" }, "publishedAt": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "type": "string" } } }, "GetApiStatutoryEffectiveResponseCompanyTaxRatesItem": { "type": "object", "properties": { "effectiveFromYearEnd": { "type": "string", "format": "date" }, "ratePercent": { "type": "number" }, "source": { "type": "string" }, "notes": { "type": "string" } } }, "GetApiStatutoryEffectiveResponseDividendsTaxRatesItem": { "type": "object", "properties": { "effectiveFrom": { "type": "string", "format": "date" }, "ratePercent": { "type": "number" } } }, "GetApiStatutoryEffectiveResponseEtiBandsItem": { "type": "object", "properties": { "label": { "type": "string" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": "string", "format": "date" }, "ceiling": { "type": "number" }, "band1Top": { "type": "number" }, "band2Top": { "type": "number" }, "year1Rate": { "type": "number" }, "year1Max": { "type": "number" }, "year1Taper": { "type": "number" }, "year2Rate": { "type": "number" }, "year2Max": { "type": "number" }, "year2Taper": { "type": "number" }, "wageFloorNoMeasure": { "type": "number" }, "source": { "type": "string" } } }, "GetApiStatutoryEffectiveResponseFilingDeadlinesItem": { "type": "object", "properties": { "kind": { "type": "string" }, "taxYearEndYear": { "type": "integer" }, "dueDate": { "type": "string", "format": "date" }, "periodLabel": { "type": "string" }, "source": { "type": "string" }, "publishedBy": { "type": "string" }, "publishedAt": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "type": "string" } } }, "GetApiStatutoryEffectiveResponseTaxYearsItem": { "type": "object", "properties": { "taxYearEndYear": { "type": "integer" }, "brackets": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiStatutoryEffectiveResponseTaxYearsItemBracketsItem" } }, "primaryRebate": { "type": "number" }, "secondaryRebate": { "type": "number" }, "tertiaryRebate": { "type": "number" }, "thresholdUnder65": { "type": "number" }, "threshold65To74": { "type": "number" }, "threshold75Plus": { "type": "number" }, "uifMonthlyCeiling": { "type": "number" }, "retirementDeductionAnnualCap": { "type": "number" }, "medicalCreditMember": { "type": "number" }, "medicalCreditFirstDependant": { "type": "number" }, "medicalCreditAdditionalDependant": { "type": "number" }, "travelRatePerKm": { "type": "number" }, "travelCostCeiling": { "type": "number" }, "uifRate": { "type": "number" }, "sdlRate": { "type": "number" }, "sdlAnnualExemptionThreshold": { "type": "number" }, "retirementDeductionRate": { "type": "number" }, "travelInclusionRate": { "type": "number" }, "motorMonthlyRate": { "type": "number" }, "motorMonthlyRateMaintained": { "type": "number" }, "motorRemunerationInclusionRate": { "type": "number" }, "accommodationAbatement": { "type": "number" }, "source": { "type": "string" }, "effectiveFrom": { "type": "string", "format": "date" }, "publishedBy": { "type": "string" }, "publishedAt": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "type": "string" } } }, "GetApiStatutoryEffectiveResponseTaxYearsItemBracketsItem": { "type": "object", "properties": { "from": { "type": "number" }, "to": { "type": "number" }, "rate": { "type": "number" }, "baseTax": { "type": "number" } } }, "GetApiStatutoryEffectiveResponseVatRatesItem": { "type": "object", "properties": { "effectiveFrom": { "type": "string", "format": "date" }, "ratePercent": { "type": "number" }, "source": { "type": "string" }, "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" } } }, "GetApiSyncPullResponseOperationsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "entityType": { "type": "string" }, "entityId": { "type": "string" }, "operation": { "type": "string" }, "payload": { "type": "string" }, "vectorClock": { "type": "string" }, "timestamp": { "type": "integer" } } }, "GetApiTenantEntitlementsResponse": { "description": "Shared by 3 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 3 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" } } }, "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" } } }, "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" } } }, "GetAuthSsoProvidersResponseItem": { "description": "Shared by 6 operations.", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } } }, "GetBillingOrdersByRefResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "publicRef": { "type": "string" }, "plan": { "type": "string" }, "planDisplayName": { "type": "string" }, "termMonths": { "type": "integer" }, "amountCents": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string" }, "email": { "type": "string" }, "licenseCode": { "type": "string" }, "licenseEmailSent": { "type": "boolean" }, "appliedToTenant": { "type": "boolean" }, "failureReason": { "type": "string" }, "kind": { "type": "string" }, "processingMode": { "type": "string" }, "createdAt": { "type": "string" }, "paidAt": { "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/GetAuthSsoProvidersResponseItem" } }, "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/PostStatusSubscribeRequest" }, "changes": { "$ref": "#/components/schemas/PostStatusSubscribeRequest" }, "baseUpdatedAt": { "type": "string" }, "conflicts": { "type": "array", "items": { "type": "object" } } } }, "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" } } } }, "PostApiBankRulesApplyRequest": { "description": "Shared by 4 operations.", "type": "object", "properties": { "bankAccountId": { "type": "string" } } }, "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 2 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" } } }, "PostApiBillingCheckoutResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "orderId": { "type": "string" }, "publicRef": { "type": "string" }, "plan": { "type": "string" }, "planDisplayName": { "type": "string" }, "termMonths": { "type": "integer" }, "amountCents": { "type": "integer" }, "currency": { "type": "string" }, "redirectUrl": { "type": "string" }, "creditCents": { "type": "integer" }, "settledWithCredit": { "type": "boolean" }, "validUntil": { "type": "string", "format": "date" } } }, "PostApiBillsByIdRejectRequest": { "description": "Shared by 8 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" } } }, "PostApiBillsByIdRejectResponseApprovalProgress": { "description": "Shared by 2 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" } } }, "PostApiBillsPaymentRunsResponse": { "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" }, "billCount": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBillsPaymentRunsResponseLinesItem" } }, "createdByName": { "type": "string" }, "createdAt": { "type": "string" }, "fileName": { "type": "string" } } }, "PostApiBillsPaymentRunsResponseLinesItem": { "description": "Shared by 2 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" } } }, "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" } } }, "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" } } }, "PostApiChannelsResponse": { "description": "Shared by 2 operations.", "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" } } }, "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" } } }, "PostApiContactsMergeResponseMergesItemMoved": { "description": "Shared by 2 operations.", "type": "object", "properties": { "invoices": { "type": "integer" } } }, "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" } } }, "PostApiCrmLeadsResponse": { "description": "Shared by 4 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 6 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 6 operations.", "type": "object", "properties": { "revenue": { "type": "number" }, "cost": { "type": "number" }, "profit": { "type": "number" }, "marginPct": { "type": "number" }, "costKnownForAllLines": { "type": "boolean" } } }, "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" } } }, "PostApiEmployeesResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "employeeNumber": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "idNumber": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date" }, "employmentType": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "terminationReason": { "type": "string" }, "jobTitle": { "type": "string" }, "department": { "type": "string" }, "costCentreId": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "bankName": { "type": "string" }, "bankAccountNumber": { "type": "string" }, "bankBranchCode": { "type": "string" }, "taxNumber": { "type": "string" }, "uifLiable": { "type": "boolean" }, "basicSalary": { "type": "number" }, "travelAllowance": { "type": "number" }, "pensionContribution": { "type": "number" }, "medicalAidContribution": { "type": "number" }, "medicalAidMembers": { "type": "integer" }, "travelInclusionRate": { "type": "number" }, "leaveBalances": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiEmployeesResponseLeaveBalancesItem" } }, "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" } } }, "PostApiExpensesCategoriesResponse": { "description": "Shared by 2 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" } } }, "PostApiExpensesReceiptsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "id": { "type": "string" }, "receiptUrl": { "type": "string" }, "contentType": { "type": "string" }, "base64": { "type": "string" } } }, "PostApiExpensesResponse": { "description": "Shared by 2 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" }, "vehicleId": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "tripId": { "type": "string" }, "tripNumber": { "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" }, "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" }, "clientId": { "type": "string" } } }, "PostApiIntercompanyTransactionsResponse": { "description": "Shared by 6 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" } } }, "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" } } }, "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/PostApiInventoryProductsResponseUnits" }, "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" } } }, "PostApiInventoryProductsResponseUnits": { "description": "Shared by 2 operations.", "type": "object", "properties": { "key": { "type": "number" } } }, "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" } } }, "PostApiInvoicesByIdApplyDepositRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "invoiceId": { "type": "string" } } }, "PostApiInvoicesByIdSendRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "channel": { "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" } } }, "PostApiInvoicesRequestDeposit": { "description": "Shared by 10 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 10 operations.", "type": "object", "properties": { "warehouse": { "type": "string" }, "picker": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiInvoicesRequestPickingLinesItem" } } } }, "PostApiInvoicesRequestPickingLinesItem": { "description": "Shared by 10 operations.", "type": "object", "properties": { "idx": { "type": "integer" }, "picked": { "type": "boolean" } } }, "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" } } }, "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" } } }, "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 22 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 22 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 22 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 23 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 22 operations.", "type": "object", "properties": { "fromStatus": { "type": "string" }, "toStatus": { "type": "string" }, "note": { "type": "string" }, "changedByName": { "type": "string" }, "at": { "type": "string" } } }, "PostApiJobCardsResponseTechniciansItem": { "description": "Shared by 22 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" } } }, "PostApiLedgerCostCentresRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "parentId": { "type": "string" }, "isActive": { "type": "boolean" } } }, "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" } } }, "PostApiLedgerJournalsByIdReverseRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "date": { "type": "string", "format": "date" } } }, "PostApiLedgerJournalsRequestLinesItem": { "description": "Shared by 5 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 5 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 3 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" } } }, "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" } } }, "PostApiMigrationApplyBillsRequest": { "description": "Shared by 4 operations.", "type": "object", "properties": { "csvContent": { "type": "string" } } }, "PostApiMigrationApplyBillsResponse": { "description": "Shared by 4 operations.", "type": "object", "properties": { "created": { "type": "integer" }, "skipped": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object" } }, "notes": { "type": "array", "items": { "type": "string" } } } }, "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" } } }, "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 12 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" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } } }, "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" }, "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" }, "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" } } }, "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" } } }, "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" } } }, "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 3 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" } } }, "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" } } }, "PostApiPushTokensResponse": { "description": "Shared by 56 operations.", "type": "object", "properties": { "status": { "type": "string" } } }, "PostApiReconciliationByIdClearRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "transactionIds": { "type": "array", "items": { "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" } } }, "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" } } }, "PostApiSarsDocumentsDividendsResponse": { "description": "Shared by 2 operations.", "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" } } }, "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" } } }, "PostApiSarsIrp6SubmitResponse": { "description": "Shared by 8 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" } } }, "PostApiSarsSubmissionsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "submissionType": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" } } }, "PostApiSarsTransmissionsByIdPollResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "transmissionId": { "type": "string" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "sarsReference": { "type": "string" }, "message": { "type": "string" }, "testSubmission": { "type": "boolean" }, "unmappedFields": { "type": "array", "items": { "type": "string" } } } }, "PostApiSetupProgressDashboardLayoutRequestCardsItem": { "type": "object", "properties": { "key": { "type": "string" }, "hidden": { "type": "boolean" } } }, "PostApiTenantAddonsResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "entitlements": { "$ref": "#/components/schemas/PostApiTenantAddonsResponseEntitlements" }, "quotedCents": { "type": "integer" }, "orderId": { "type": "string" }, "checkoutUrl": { "type": "string" }, "message": { "type": "string" } } }, "PostApiTenantAddonsResponseEntitlements": { "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" }, "storageUsedLabel": { "type": "string" }, "storageHeadroomLabel": { "type": "string" }, "storageUsedFraction": { "type": "number" }, "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/PostApiTenantAddonsResponseEntitlementsAddonsItem" } }, "availableAddons": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiTenantAddonsResponseEntitlementsAddonsItem" } }, "addonsMonthlyTotal": { "type": "number" }, "addonUpgradeSuggestion": { "type": "string" }, "apiKeysUsed": { "type": "integer" }, "apiKeysIncluded": { "type": "integer" }, "apiKeysHeadroom": { "type": "integer" }, "apiKeysSummary": { "type": "string" } } }, "PostApiTenantAddonsResponseEntitlementsAddonsItem": { "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" }, "proRataCents": { "type": "integer" }, "proRataNote": { "type": "string" }, "pendingOrderId": { "type": "string" }, "pendingCheckoutUrl": { "type": "string" }, "pendingAmountCents": { "type": "integer" } } }, "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" } } }, "PostApiTimeTrackingProjectsResponse": { "description": "Shared by 2 operations.", "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" } } }, "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 5 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" } } }, "PostAuthClaimEmailRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "token": { "type": "string" } } }, "PostAuthClaimEmailResponse": { "description": "Shared by 2 operations.", "type": "object", "properties": { "email": { "type": "string" }, "verified": { "type": "boolean" }, "released": { "type": "boolean" } } }, "PostAuthLoginResponse": { "description": "Shared by 3 operations.", "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" } } }, "PostAuthLogoutResponse": { "description": "Shared by 6 operations.", "type": "object", "properties": { "message": { "type": "string" } } }, "PostAuthValidateLicenseRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "licenseCode": { "type": "string" } } }, "PostCommunityQuestionsResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "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 3 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" } } }, "PostStatusSubscribeRequest": { "description": "Shared by 5 operations.", "type": "object", "properties": { "email": { "type": "string" } } }, "PostStatusSubscribeResponse": { "description": "Shared by 3 operations.", "type": "object", "properties": { "received": { "type": "boolean" }, "message": { "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" } } }, "PostTrackByTokenUpdatesRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "optedOut": { "type": "boolean" } } }, "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" } } }, "PutApiCrmActivitiesByIdResponse": { "description": "Shared by 2 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" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } } }, "PutApiPayrollSettingsRequestBanking": { "description": "Shared by 4 operations.", "type": "object", "properties": { "payingBankAccountId": { "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" } } }, "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" } } }, "PutApiReminderConfigsRequest": { "description": "Shared by 2 operations.", "type": "object", "properties": { "enabled": { "type": "boolean" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/PutApiReminderConfigsRequestStepsItem" } }, "message": { "type": "string" } } }, "PutApiReminderConfigsRequestStepsItem": { "description": "Shared by 2 operations.", "type": "object", "properties": { "days": { "type": "integer" }, "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" } } }, "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" }, "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" } } } }, "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 ] } ] }, "GetApiBillingSubscriptionResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "plan": "business", "planDisplayName": "Karoo Fresh Holdings Ltd", "termMonths": 1, "status": "sent", "autoRenew": true, "currentPeriodStart": "2026-09-01", "currentPeriodEnd": "2026-09-30", "nextRenewalOn": "2026-09-01", "daysUntilRenewal": 30, "renewalAmountCents": 49900, "pendingOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "pendingCheckoutUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "summary": "Consulting services — August 2026", "cancelsOn": "2026-09-01", "cancellationNotice": "This run includes a catch-up deduction; the year-to-date total is correct." } }, "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@capeunionmart.co.za", "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" } }, "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." } } }, "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" } }, "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" } }, "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 } ] } }, "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 } ] }, "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" } ], "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 } ] }, "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@capeunionmart.co.za", "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 } ], "interimPaye": 1.0, "interimUif": 1.0, "interimSdl": 1.0, "interimEti": 1.0, "interimTotal": 10005.0, "annualPaye": 1.0, "annualUif": 1.0, "annualSdl": 1.0, "annualEti": 1.0, "annualTotal": 10005.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 2 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" } ], "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 } }, "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" }, "payingBankAccountOptions": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "label": "Karoo Fresh Holdings Ltd", "accountMasked": "text", "bankName": "FNB" } ] } }, "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 }, "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.co.za", "inviteeName": "Thabo Nkosi", "assigned": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Ayesha Patel", "email": "ayesha@mokoenapartners.co.za", "roleName": "Accountant", "isSelf": false } ], "roster": [ { "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Ayesha Patel", "email": "ayesha@mokoenapartners.co.za", "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." } }, "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" } ] } }, "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." } }, "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 6 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": "sent", "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "GetApiReportsAfsSettingsResponseExample": { "description": "Shared by 2 operations.", "value": { "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.", "averageEmployees": 1, "beneficialInterestHolders": 1, "internallyCompiled": true, "ownerManaged": false } }, "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 } }, "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 5 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 } }, "GetApiStatutoryEffectiveResponseExample": { "value": { "revision": "text", "taxYears": [ { "taxYearEndYear": 2026, "brackets": [ { "from": 1.0, "to": 1.0, "rate": 15.0, "baseTax": 1305.0 } ], "primaryRebate": 1.0, "secondaryRebate": 1.0, "tertiaryRebate": 1.0, "thresholdUnder65": 1.0, "threshold65To74": 1.0, "threshold75Plus": 1.0, "uifMonthlyCeiling": 1.0, "retirementDeductionAnnualCap": 1.0, "medicalCreditMember": 1.0, "medicalCreditFirstDependant": 1.0, "medicalCreditAdditionalDependant": 1.0, "travelRatePerKm": 1.0, "travelCostCeiling": 10005.0, "uifRate": 15.0, "sdlRate": 15.0, "sdlAnnualExemptionThreshold": 1.0, "retirementDeductionRate": 15.0, "travelInclusionRate": 15.0, "motorMonthlyRate": 15.0, "motorMonthlyRateMaintained": 1.0, "motorRemunerationInclusionRate": 15.0, "accommodationAbatement": 1.0, "source": "referral", "effectiveFrom": "2026-09-01", "publishedBy": "text", "publishedAt": "2026-09-01T09:15:00Z", "active": true, "notes": "Budget deferred to the next financial year." } ], "vatRates": [ { "effectiveFrom": "2026-09-01", "ratePercent": 15.0, "source": "referral", "notes": "Budget deferred to the next financial year." } ], "companyTaxRates": [ { "effectiveFromYearEnd": "2026-09-30", "ratePercent": 15.0, "source": "referral", "notes": "Budget deferred to the next financial year." } ], "calendarDays": [ { "date": "2026-09-01", "name": "Karoo Fresh Holdings Ltd", "kind": "standard", "source": "referral", "publishedBy": "text", "publishedAt": "2026-09-01T09:15:00Z", "active": true, "notes": "Budget deferred to the next financial year." } ], "filingDeadlines": [ { "kind": "standard", "taxYearEndYear": 2026, "dueDate": "2026-09-01", "periodLabel": "2026-09", "source": "referral", "publishedBy": "text", "publishedAt": "2026-09-01T09:15:00Z", "active": true, "notes": "Budget deferred to the next financial year." } ], "dividendsTaxRates": [ { "effectiveFrom": "2026-09-01", "ratePercent": 15.0 } ], "etiBands": [ { "label": "Karoo Fresh Holdings Ltd", "effectiveFrom": "2026-09-01", "effectiveTo": "2026-09-30", "ceiling": 1.0, "band1Top": 1.0, "band2Top": 1.0, "year1Rate": 15.0, "year1Max": 1.0, "year1Taper": 1.0, "year2Rate": 15.0, "year2Max": 1.0, "year2Taper": 1.0, "wageFloorNoMeasure": 1.0, "source": "referral" } ] } }, "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" } }, "GetApiTenantEntitlementsResponseExample": { "description": "Shared by 2 operations.", "value": { "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" } }, "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 } } }, "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" } ] } }, "GetBillingOrdersByRefResponseExample": { "description": "Shared by 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "publicRef": "INV-0001", "plan": "business", "planDisplayName": "Karoo Fresh Holdings Ltd", "termMonths": 1, "amountCents": 49900, "currency": "ZAR", "status": "sent", "email": "accounts@capeunionmart.co.za", "licenseCode": "CT-001", "licenseEmailSent": false, "appliedToTenant": false, "failureReason": "Budget deferred to the next financial year.", "kind": "standard", "processingMode": "text", "createdAt": "2026-09-01T09:15:00Z", "paidAt": "2026-09-01T09:15:00Z" } }, "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.co.za" }, "changes": { "email": "finance@capeunion.co.za" }, "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": "sent", "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 } }, "PostApiBillingCheckoutResponseExample": { "description": "Shared by 3 operations.", "value": { "orderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "publicRef": "INV-0001", "plan": "business", "planDisplayName": "Karoo Fresh Holdings Ltd", "termMonths": 1, "amountCents": 49900, "currency": "ZAR", "redirectUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "creditCents": 49900, "settledWithCredit": false, "validUntil": "2026-09-30" } }, "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" } }, "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" } ], "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 } } }, "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" } ], "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" } }, "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": "INV-0001", "payeNumber": "INV-0001", "uifNumber": "INV-0001", "sdlNumber": "INV-0001", "tradingAs": "text", "email": "accounts@capeunionmart.co.za", "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" } }, "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@capeunionmart.co.za", "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 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "firstName": "Karoo Fresh Holdings Ltd", "lastName": "Karoo Fresh Holdings Ltd", "idNumber": "INV-0001", "dateOfBirth": "1988-04-12", "employmentType": "standard", "startDate": "2026-09-01", "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@capeunionmart.co.za", "phone": "+27 82 555 0143", "bankName": "FNB", "bankAccountNumber": "62012345678", "bankBranchCode": "250655", "taxNumber": "INV-0001", "uifLiable": true, "basicSalary": 1.0, "travelAllowance": 1.0, "pensionContribution": 1.0, "medicalAidContribution": 1.0, "medicalAidMembers": 1, "travelInclusionRate": 15.0, "leaveBalances": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leaveType": "annual", "balanceDays": 10005.0, "takenDays": 1.0 } ], "createdAt": "2026-09-01T09:15:00Z", "updatedAt": "2026-09-01T09:15:00Z" } }, "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==" } }, "PostApiExpensesResponseExample": { "description": "Shared by 2 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", "vehicleId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "vehicleRegistration": "text", "tripId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripNumber": "INV-0001" } }, "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, "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 5 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" } }, "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" } }, "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" } ], "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" } }, "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 3 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 } }, "PostApiLedgerPeriodsResponseExample": { "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" } }, "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@capeunionmart.co.za", "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@capeunionmart.co.za", "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@capeunionmart.co.za", "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" } }, "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@capeunionmart.co.za", "contactPhone": "+27 82 555 0143", "remittanceEmail": "accounts@capeunionmart.co.za", "notes": "Budget deferred to the next financial year.", "isActive": true, "memberCount": 3 } }, "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": "text", "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." } }, "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, "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 } }, "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@capeunionmart.co.za", "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": "aura:day:loc-main:2026-10-01:r1", "standardRatedNetCents": 99565, "zeroRatedCents": 0, "outputVatCents": 14935, "inputVatCents": 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 2 operations.", "value": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "practitionerEmail": "accounts@capeunionmart.co.za", "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@capeunionmart.co.za", "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 } }, "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" } }, "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 7 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" } }, "PostApiSarsTransmissionsByIdPollResponseExample": { "description": "Shared by 2 operations.", "value": { "transmissionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "status": "sent", "statusLabel": "Karoo Fresh Holdings Ltd", "sarsReference": "INV-0001", "message": "Saved.", "testSubmission": true, "unmappedFields": [ "text" ] } }, "PostApiTenantAddonsResponseExample": { "description": "Shared by 2 operations.", "value": { "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, "storageUsedLabel": "Karoo Fresh Holdings Ltd", "storageHeadroomLabel": "Karoo Fresh Holdings Ltd", "storageUsedFraction": 1.0, "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", "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 } ], "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", "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 } ], "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" }, "quotedCents": 49900, "orderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "checkoutUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "message": "Saved." } }, "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 } ] } }, "PostAuthLoginResponseExample": { "description": "Shared by 2 operations.", "value": { "accessToken": "", "refreshToken": "", "userId": "05aea44f-e1a0-5fc5-a870-df0697216af5", "tenantId": "f80b8d0f-4c0f-58e9-80a4-5915fa569c52", "tenantName": "Your Business", "email": "you@example.co.za", "role": "owner", "firstName": "Andy", "lastName": "Cameron", "mustEnroll2fa": false, "mustChangePassword": false } }, "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" } }, "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" } }, "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" } }, "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, "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/register": { "post": { "tags": [ "Authentication" ], "summary": "Create a tenant and its first user. Returns a JWT.", "operationId": "postAuthRegister", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "licenseCode": { "type": "string" }, "tenantName": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "companyProfile": { "type": "object", "properties": { "businessType": { "type": "string" }, "cipcNumber": { "type": "string" }, "vatNumber": { "type": "string" }, "vatCategory": { "type": "string" }, "incomeTaxNumber": { "type": "string" }, "payeNumber": { "type": "string" }, "address": { "type": "string" }, "phone": { "type": "string" }, "financialYearEnd": { "type": "string", "format": "date" }, "bankProfileCode": { "type": "string" }, "migrationSource": { "type": "string" } } }, "deviceId": { "type": "string" }, "devicePlatform": { "type": "string" } } }, "example": { "licenseCode": "", "tenantName": "Cape Fine Foods", "email": "accounts@capeunionmart.co.za", "password": "2e1167ef9d17bf3d4bb558dc6a88e9b822d298a8837447f6d9ac3de7e592d909", "firstName": "Andy", "lastName": "Cameron", "companyProfile": { "businessType": "standard", "cipcNumber": "INV-0001", "vatNumber": "4123456789", "vatCategory": "Office supplies", "incomeTaxNumber": "INV-0001", "payeNumber": "INV-0001", "address": "12 Long Street, Cape Town, 8001", "phone": "+27 82 555 0143", "financialYearEnd": "2026-09-30", "bankProfileCode": "CT-001", "migrationSource": "referral" }, "deviceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "devicePlatform": "android" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthLoginResponse" }, "example": { "accessToken": "", "refreshToken": "", "userId": "aa12b271-1bb7-5779-9c1f-5cfe628c52da", "tenantId": "a5cc09c7-c515-5872-8115-ad8cf00c5201", "tenantName": "Your Business", "email": "you@example.co.za", "role": "owner", "firstName": "Andy", "lastName": "Cameron", "mustEnroll2fa": false, "mustChangePassword": false } } } } } } }, "/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.co.za", "password": "your-password", "totpCode": "123456", "deviceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "devicePlatform": "android" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthLoginResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostAuthLoginResponseExample" } } } } } } } }, "/auth/sso/providers": { "get": { "tags": [ "Authentication" ], "summary": "Which providers this deployment offers for signing in (google, microsoft). A client draws a sign-in button only for these.", "operationId": "getAuthSsoProviders", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetAuthSsoProvidersResponseItem" } }, "example": [ { "id": "google", "label": "Google" } ] } } } } } }, "/auth/sso/{provider}": { "post": { "tags": [ "Authentication" ], "summary": "Sign in with a Google or Microsoft ID token. It must be signed by the provider, issued to Ledgr and current, and the account must have been linked by its owner from a signed-in session (POST /api/me/sso-identities/{provider}); nothing is matched by email. Everything after that is the password sign-in: lockout, two-factor (an ID token does not prove a second factor, so an enrolled person still sends totpCode), the device cap and the session. Answers exactly as POST /auth/login.", "operationId": "postAuthSsoByProvider", "security": [], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idToken": { "type": "string" }, "totpCode": { "type": "string" }, "deviceId": { "type": "string" }, "devicePlatform": { "type": "string" } } }, "example": { "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImsxIn0.eyJzdWIiOiIxMDk4NzY1NDMyMTAiLCJhdWQiOiJsZWRnciJ9.c2lnbmF0dXJl", "totpCode": "123456", "deviceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "devicePlatform": "android" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthLoginResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostAuthLoginResponseExample" } } } } } } } }, "/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@capeunionmart.co.za", "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@capeunionmart.co.za", "role": "Accountant" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/auth/password": { "post": { "tags": [ "Authentication" ], "summary": "Replace the signed-in user's own password. Needs the current one. Clears mustChangePassword, which an invitation's temporary password sets.", "operationId": "postAuthPassword", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string" }, "newPassword": { "type": "string" } } }, "example": { "currentPassword": "", "newPassword": "" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "changed": { "type": "boolean" } } }, "example": { "changed": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/auth/forgot-password": { "post": { "tags": [ "Authentication" ], "summary": "Send a password-reset email. Answers identically whether or not the address exists, so it cannot be probed for.", "operationId": "postAuthForgotPassword", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostStatusSubscribeRequest" }, "example": { "email": "you@example.co.za" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthLogoutResponse" }, "example": { "message": "If that email is registered you will receive a reset link shortly." } } } } } } }, "/auth/reset-password": { "post": { "tags": [ "Authentication" ], "summary": "Set a new password from the token in the reset email.", "operationId": "postAuthResetPassword", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "newPassword": { "type": "string" } } }, "example": { "token": "", "newPassword": "2e1167ef9d17bf3d4bb558dc6a88e9b822d298a8837447f6d9ac3de7e592d909" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthLogoutResponse" }, "example": { "message": "Password updated successfully. You can now log in with your new password." } } } } } } }, "/auth/validate-license": { "post": { "tags": [ "Authentication" ], "summary": "Check a licence key without redeeming it — the plan it carries, its seats and its expiry.", "operationId": "postAuthValidateLicense", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthValidateLicenseRequest" }, "example": { "licenseCode": "LEDGR-7F3A-91C2-4B8E" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "plan": { "type": "string" }, "message": { "type": "string" } } }, "example": { "valid": true, "plan": "business", "message": "Saved." } } } } } } }, "/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." } } } }, "/reset-password": { "get": { "tags": [ "Authentication" ], "summary": "The password-reset page the emailed link opens. HTML, not JSON.", "operationId": "getResetPassword", "security": [], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } } }, "/auth/verify-email": { "post": { "tags": [ "Authentication" ], "summary": "Confirm a login's email address from the token in the verification email. Until it is confirmed, the account's notices and billing mail wait.", "operationId": "postAuthVerifyEmail", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthClaimEmailRequest" }, "example": { "token": "" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthClaimEmailResponse" }, "example": { "email": "thandi@example.co.za", "verified": true, "released": false } } } } } } }, "/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" } } } }, "/auth/claim-email": { "post": { "tags": [ "Authentication" ], "summary": "Release an address that an unconfirmed account is holding, from the token mailed to it when somebody tried to register it. A confirmed holder is never released.", "operationId": "postAuthClaimEmail", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthClaimEmailRequest" }, "example": { "token": "" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthClaimEmailResponse" }, "example": { "email": "thandi@example.co.za", "verified": false, "released": true } } } } } } }, "/verify-email": { "get": { "tags": [ "Authentication" ], "summary": "The page the verification email's link opens. HTML, not JSON.", "operationId": "getVerifyEmail", "security": [], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } } }, "/claim-email": { "get": { "tags": [ "Authentication" ], "summary": "The page the release email's link opens. HTML, not JSON.", "operationId": "getClaimEmail", "security": [], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } } }, "/api/me/sso-identities": { "get": { "tags": [ "Two-factor authentication" ], "summary": "The Google and Microsoft accounts the signed-in person has linked for signing in. The email is for display only.", "operationId": "getApiMeSsoIdentities", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiMeSsoIdentitiesResponseItem" } }, "example": [ { "provider": "google", "email": "you@example.co.za", "linkedAt": "2026-10-11T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/me/sso-identities/{provider}": { "post": { "tags": [ "Two-factor authentication" ], "summary": "Link the provider account an ID token belongs to, to the signed-in person. One provider account links to one person across every business: a second person is refused with 409. Linking another account for the same provider replaces the first.", "operationId": "postApiMeSsoIdentitiesByProvider", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idToken": { "type": "string" } } }, "example": { "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImsxIn0.eyJzdWIiOiIxMDk4NzY1NDMyMTAiLCJhdWQiOiJsZWRnciJ9.c2lnbmF0dXJl" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiMeSsoIdentitiesResponseItem" }, "example": { "provider": "google", "email": "you@example.co.za", "linkedAt": "2026-10-11T09:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Two-factor authentication" ], "summary": "Unlink the signed-in person's account for this provider. It signs nobody in from then on.", "operationId": "deleteApiMeSsoIdentitiesByProvider", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/2fa/me": { "get": { "tags": [ "Two-factor authentication" ], "summary": "Whether this user is enrolled, when they enrolled, and how many recovery codes are unused.", "operationId": "getApi2faMe", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrolled": { "type": "boolean" }, "lastVerifiedAt": { "type": "string" }, "recoveryCodesRemaining": { "type": "integer" } } }, "example": { "enrolled": true, "lastVerifiedAt": "2026-09-01T09:15:00Z", "recoveryCodesRemaining": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Two-factor authentication" ], "summary": "Disenrol, using the user's own current code.", "operationId": "deleteApi2faMe", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "code", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "123456" } ], "responses": { "204": { "description": "Done. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/2fa/enroll": { "post": { "tags": [ "Two-factor authentication" ], "summary": "Start enrolment. Returns the TOTP secret, the otpauth:// URI and ten recovery codes — the codes are shown ONCE and stored hashed, so no endpoint can ever show them again.", "operationId": "postApi2faEnroll", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "code", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "123456" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" }, "otpauthUrl": { "type": "string" } } }, "example": { "secret": "", "otpauthUrl": "https://app.ledgrsa.com/pay/3f1a7c92" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/2fa/verify": { "post": { "tags": [ "Two-factor authentication" ], "summary": "Confirm enrolment with a code from the authenticator app.", "operationId": "postApi2faVerify", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } } }, "example": { "code": "123456" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "message": { "type": "string" }, "recoveryCodes": { "type": "array", "items": { "type": "string" } } } }, "example": { "verified": true, "message": "Saved.", "recoveryCodes": [ "CT-001" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/2fa/recovery-codes": { "post": { "tags": [ "Two-factor authentication" ], "summary": "Mint a fresh set of ten recovery codes. Every previously issued code stops working.", "operationId": "postApi2faRecoveryCodes", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "code", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "123456" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" } }, "generatedAt": { "type": "string" } } }, "example": { "codes": [ "CT-001" ], "generatedAt": "2026-09-01T09:15:00Z" } } } }, "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@capeunionmart.co.za", "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" }, "examples": { "default": { "$ref": "#/components/examples/GetApiTenantEntitlementsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/tenant/apply-license": { "post": { "tags": [ "Tenant, plan & entitlements" ], "summary": "Redeem a licence key against this tenant. A dated key creates a subscription with auto_renew off, so it announces its expiry rather than lapsing in silence.", "operationId": "postApiTenantApplyLicense", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAuthValidateLicenseRequest" }, "example": { "licenseCode": "LEDGR-7F3A-91C2-4B8E" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiTenantEntitlementsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiTenantEntitlementsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/tenant/addons": { "post": { "tags": [ "Tenant, plan & entitlements" ], "summary": "Buy or resize an add-on. V333: the part-period is charged FIRST — the response carries a Yoco checkout for the days remaining in the term already paid for, and the add-on is granted only once that is settled, so a mid-term purchase can no longer be had free until the next renewal. Where there is nothing chargeable (below the R5.00 minimum, or a licence with no expiry) it applies immediately and `applied` is true. Needs roles:edit, because it changes what the tenant pays. Quantity is at least 1: removing an add-on is a DELETE, since a zero-quantity holding would grant nothing and still bill. The whole entitlements document is nested in the reply, so the caller never re-reads it.", "operationId": "postApiTenantAddons", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addonId": { "type": "string" }, "quantity": { "type": "integer" } } }, "example": { "addonId": "logistics", "quantity": 1 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiTenantAddonsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiTenantAddonsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/tenant/addons/{addonId}": { "delete": { "tags": [ "Tenant, plan & entitlements" ], "summary": "Stop an add-on. Free and immediate — only taking one on is charged. Cancelled rather than deleted: a holding kept for four months of a twelve-month term is part of explaining that term's invoice, and a row that is gone cannot explain a charge the customer is looking at. Any unpaid part-period checkout for it is cancelled at the same time, or the customer could pay for something they have just switched off. The updated entitlements are nested in the reply.", "operationId": "deleteApiTenantAddonsByAddonId", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "addonId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiTenantAddonsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiTenantAddonsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/plans": { "get": { "tags": [ "Tenant, plan & entitlements" ], "summary": "The price list as the server holds it — every plan, its price, its seats and its modules. Prices exclude VAT.", "operationId": "getApiPlans", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "modules": { "type": "array", "items": { "type": "string" } }, "priceMonthly": { "type": "number" }, "maxUsers": { "type": "integer" }, "maxCompanies": { "type": "integer" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "displayName": "Karoo Fresh Holdings Ltd", "modules": [ "invoices" ], "priceMonthly": 10005.0, "maxUsers": 1, "maxCompanies": 1 } ] } } }, "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/setup-progress": { "get": { "tags": [ "Tenant, plan & entitlements" ], "summary": "The dashboard checklist. Four of the five steps are detected live from the books rather than trusted from a flag; completion is per tenant, hiding is per user.", "operationId": "getApiSetupProgress", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSetupProgressResponse" }, "example": { "completedKeys": [ "text" ], "markedKeys": [ "text" ], "detectedKeys": [ "text" ], "checklistHidden": false } } } }, "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/setup-progress/steps": { "post": { "tags": [ "Tenant, plan & entitlements" ], "summary": "Mark the one step nothing can detect — that a migration from the previous system has been done.", "operationId": "postApiSetupProgressSteps", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stepKey": { "type": "string" }, "complete": { "type": "boolean" } } }, "example": { "stepKey": "invoice", "complete": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSetupProgressResponse" }, "example": { "completedKeys": [ "text" ], "markedKeys": [ "text" ], "detectedKeys": [ "text" ], "checklistHidden": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/setup-progress/hidden": { "post": { "tags": [ "Tenant, plan & entitlements" ], "summary": "Hide the checklist for the calling user only. One colleague cannot dismiss it for another.", "operationId": "postApiSetupProgressHidden", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hidden": { "type": "boolean" } } }, "example": { "hidden": true } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiSetupProgressResponse" }, "example": { "completedKeys": [ "text" ], "markedKeys": [ "text" ], "detectedKeys": [ "text" ], "checklistHidden": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/setup-progress/dashboard-layout": { "post": { "tags": [ "Tenant, plan & entitlements" ], "summary": "Arrange the calling user's dashboard: the cards in order, and which they have hidden. Per user. Refused when a card is unknown, named twice, or every card is hidden; a partial list is completed with the missing cards shown.", "operationId": "postApiSetupProgressDashboardLayout", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cards": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiSetupProgressDashboardLayoutRequestCardsItem" } } } }, "example": { "cards": [ { "key": "invoices-tax", "hidden": false }, { "key": "kpis", "hidden": false }, { "key": "insights", "hidden": true } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "completedKeys": { "type": "array", "items": { "type": "string" } }, "markedKeys": { "type": "array", "items": { "type": "object" } }, "detectedKeys": { "type": "array", "items": { "type": "string" } }, "checklistHidden": { "type": "boolean" }, "dashboardLayout": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiSetupProgressDashboardLayoutRequestCardsItem" } } } }, "example": { "completedKeys": [ "company" ], "markedKeys": [], "detectedKeys": [ "company" ], "checklistHidden": false, "dashboardLayout": [ { "key": "invoices-tax", "hidden": false }, { "key": "bank-cash-flow", "hidden": false }, { "key": "job-cards", "hidden": false }, { "key": "operations", "hidden": false }, { "key": "kpis", "hidden": false }, { "key": "revenue-expenses", "hidden": false }, { "key": "insights", "hidden": false }, { "key": "recent-activity", "hidden": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/academy": { "get": { "tags": [ "Tenant, plan & entitlements" ], "summary": "Ledgr Academy for the calling user: every published course and lesson with its three questions and their options (never which option is right), which lessons the caller has passed, and whether each course is complete. Per user; any role, every plan.", "operationId": "getApiAcademy", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "courses": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "intro": { "type": "string" }, "lessons": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "goal": { "type": "string" }, "duration": { "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } } } }, "passed": { "type": "boolean" } } } }, "lessonsPassed": { "type": "integer" }, "complete": { "type": "boolean" } } } }, "lessonsPassed": { "type": "integer" }, "lessonsTotal": { "type": "integer" } } }, "example": { "courses": [ { "slug": "sales", "title": "Sales", "intro": "text", "lessons": [ { "slug": "raise-and-send-an-invoice", "title": "Raise and send an invoice", "goal": "text", "duration": "2:41", "questions": [ { "question": "text", "options": [ "text", "text", "text" ] } ], "passed": true } ], "lessonsPassed": 1, "complete": false } ], "lessonsPassed": 1, "lessonsTotal": 28 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/academy/lessons/{slug}/answers": { "post": { "tags": [ "Tenant, plan & entitlements" ], "summary": "Answer a lesson's questions: the index of the chosen option for each, in order. Answers whether each was right; every one right records the lesson as passed for the caller, once (answering again is not an error). Refused 400 for the wrong number of answers or an option that does not exist, 404 for an unknown lesson.", "operationId": "postApiAcademyLessonsBySlugAnswers", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "integer" } } } }, "example": { "answers": [ 1, 2, 0 ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "passed": { "type": "boolean" }, "correct": { "type": "array", "items": { "type": "boolean" } }, "courseComplete": { "type": "boolean" } } }, "example": { "passed": true, "correct": [ true, true, true ], "courseComplete": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/academy/courses/{slug}/certificate": { "get": { "tags": [ "Tenant, plan & entitlements" ], "summary": "The course certificate as a PDF, with the caller's name, the course and the date its last lesson was passed. Refused 409 until every lesson of the course is passed, saying how many are done; 404 for an unknown course.", "operationId": "getApiAcademyCoursesBySlugCertificate", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "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/data/export": { "post": { "tags": [ "Tenant, plan & entitlements" ], "summary": "A ZIP of CSVs — every table this tenant owns. 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/billing/checkout": { "post": { "tags": [ "Billing & subscription" ], "summary": "Start a purchase or an upgrade. Returns a Yoco hosted-checkout URL to redirect the buyer to.", "operationId": "postApiBillingCheckout", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "string" }, "termMonths": { "type": "integer" } } }, "example": { "planId": "business", "termMonths": 12 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillingCheckoutResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBillingCheckoutResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/billing/checkout/quote": { "get": { "tags": [ "Billing & subscription" ], "summary": "What a checkout for this plan and term will charge this business, before anybody commits: the full term, the credit for unused time on the plan being replaced, and what is actually payable. Priced by the same function the checkout uses, so the quote and the order cannot differ. Writes nothing.", "operationId": "getApiBillingCheckoutQuote", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "planId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "business" }, { "name": "termMonths", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "12" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string" }, "planDisplayName": { "type": "string" }, "termMonths": { "type": "integer" }, "fullPriceCents": { "type": "integer" }, "creditCents": { "type": "integer" }, "payableCents": { "type": "integer" }, "currency": { "type": "string" } } }, "example": { "plan": "business", "planDisplayName": "Business", "termMonths": 12, "fullPriceCents": 548900, "creditCents": 548900, "payableCents": 0, "currency": "ZAR" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/billing/orders": { "get": { "tags": [ "Billing & subscription" ], "summary": "This tenant's licence orders, paid and outstanding.", "operationId": "getApiBillingOrders", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetBillingOrdersByRefResponse" } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "publicRef": "INV-0001", "plan": "business", "planDisplayName": "Karoo Fresh Holdings Ltd", "termMonths": 1, "amountCents": 49900, "currency": "ZAR", "status": "sent", "email": "accounts@capeunionmart.co.za", "licenseCode": "CT-001", "licenseEmailSent": false, "appliedToTenant": false, "failureReason": "Budget deferred to the next financial year.", "kind": "standard", "processingMode": "text", "createdAt": "2026-09-01T09:15:00Z", "paidAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/billing/orders/{id}/pdf": { "get": { "tags": [ "Billing & subscription" ], "summary": "The invoice for a paid licence order, as a PDF — the same document the licence email carried. An invoice, not a tax invoice: the seller is not a registered VAT vendor. 404 for an order that has not been paid.", "operationId": "getApiBillingOrdersByIdPdf", "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/billing/orders/{id}": { "get": { "tags": [ "Billing & subscription" ], "summary": "One order — its amount, its state and its checkout link if it is still payable.", "operationId": "getApiBillingOrdersById", "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/GetBillingOrdersByRefResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetBillingOrdersByRefResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/billing/subscription": { "get": { "tags": [ "Billing & subscription" ], "summary": "The subscription: plan, term, current period end, whether it auto-renews, and the retention date if it has ended.", "operationId": "getApiBillingSubscription", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBillingSubscriptionResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBillingSubscriptionResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/billing/subscription/auto-renew": { "post": { "tags": [ "Billing & subscription" ], "summary": "Turn renewal on or off. One endpoint for both directions, because two would let them disagree. Cancelling means stop renewing — no refund and no revocation.", "operationId": "postApiBillingSubscriptionAutoRenew", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "autoRenew": { "type": "boolean" } } }, "example": { "autoRenew": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiBillingSubscriptionResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiBillingSubscriptionResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/billing/subscription/pay-now": { "post": { "tags": [ "Billing & subscription" ], "summary": "Settle the outstanding renewal early. A renewal EXTENDS from the existing expiry, so paying early never costs days.", "operationId": "postApiBillingSubscriptionPayNow", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillingCheckoutResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBillingCheckoutResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/billing/plans": { "get": { "tags": [ "Billing & subscription" ], "summary": "The list prices in force for every purchasable plan, with the seat and company allowances. The Free tier's terms in force ride beside the list as `free`, for the sign-up screen's Start on Free card. No authentication: it is a price list, and it is what the public pricing page reads so the figure it shows is the figure the checkout charges.", "operationId": "getBillingPlans", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "priceMonthly": { "type": "number" }, "maxUsers": { "type": "integer" }, "maxCompanies": { "type": "integer" } } } }, "free": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "priceMonthly": { "type": "number" }, "maxUsers": { "type": "integer" }, "maxCompanies": { "type": "integer" }, "monthlyInvoiceLimit": { "type": "integer" } } } } }, "example": { "plans": [ { "id": "starter", "name": "Starter", "priceMonthly": 199.0, "maxUsers": 3, "maxCompanies": 1 }, { "id": "business", "name": "Business", "priceMonthly": 499.0, "maxUsers": 10, "maxCompanies": 1 } ], "free": { "id": "free", "name": "Free", "priceMonthly": 0.0, "maxUsers": 1, "maxCompanies": 1, "monthlyInvoiceLimit": 5 } } } } } } } }, "/billing/public-checkout": { "post": { "tags": [ "Billing & subscription" ], "summary": "Buy a licence before signing up. Mints an order and a Yoco checkout without a tenant existing yet.", "operationId": "postBillingPublicCheckout", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "string" }, "termMonths": { "type": "integer" }, "email": { "type": "string" } } }, "example": { "planId": "starter", "termMonths": 1, "email": "you@example.co.za" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiBillingCheckoutResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiBillingCheckoutResponseExample" } } } } } } } }, "/billing/orders/{ref}": { "get": { "tags": [ "Billing & subscription" ], "summary": "The public state of a pre-signup order, by its reference. What the buyer's return page polls.", "operationId": "getBillingOrdersByRef", "security": [], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBillingOrdersByRefResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetBillingOrdersByRefResponseExample" } } } } } } } }, "/billing/success": { "get": { "tags": [ "Billing & subscription" ], "summary": "The buyer's return page after a successful Yoco checkout. HTML.", "operationId": "getBillingSuccess", "security": [], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } } }, "/billing/cancelled": { "get": { "tags": [ "Billing & subscription" ], "summary": "The buyer's return page after an abandoned checkout. HTML.", "operationId": "getBillingCancelled", "security": [], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } } }, "/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@capeunionmart.co.za", "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@capeunionmart.co.za", "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@capeunionmart.co.za", "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@capeunionmart.co.za", "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": { "$ref": "#/components/schemas/DeleteApiPushTokensResponse" }, "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@capeunionmart.co.za", "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@capeunionmart.co.za", "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/user-sessions": { "get": { "tags": [ "Users, roles & security" ], "summary": "Live sessions across the tenant — device, address and last seen.", "operationId": "getApiUserSessions", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "userEmail": { "type": "string" }, "ipAddress": { "type": "string" }, "userAgent": { "type": "string" }, "deviceLabel": { "type": "string" }, "devicePlatform": { "type": "string" }, "deviceCountForUser": { "type": "integer" }, "lastSeenAt": { "type": "string" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "userEmail": "accounts@capeunionmart.co.za", "ipAddress": "12 Long Street, Cape Town, 8001", "userAgent": "text", "deviceLabel": "Karoo Fresh Holdings Ltd", "devicePlatform": "text", "deviceCountForUser": 1, "lastSeenAt": "2026-09-01T09:15:00Z", "expiresAt": "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/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@capeunionmart.co.za", "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" } } }, "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" } } } }, "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: aura). 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": "aura", "ready": false, "keyName": "Aura 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.co.za/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.co.za/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/PostApiPushTokensResponse" }, "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" } } ], "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/search": { "get": { "tags": [ "Search, insights & deadlines" ], "summary": "Cross-module global search behind the search palette: documents (by number, reference, customer name or amount), contacts, expenses, bills, bank accounts and statement lines, products and employees, five of each kind, most relevant first. `more` names the kinds with further matches. Each kind is gated separately on plan modules and RBAC, so results never name a record the caller may not open.", "operationId": "getApiSearch", "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": "acme" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "module": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "date": { "type": "string", "format": "date" }, "contextId": { "type": "string" } } } }, "more": { "type": "array", "items": { "type": "string" } } } }, "example": { "query": "Karoo Fresh", "results": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "type": "invoice", "module": "invoices", "title": "INV-0001", "subtitle": "Karoo Fresh Holdings Ltd · Tax Invoice", "status": "sent", "amount": 10005.0, "currency": "ZAR", "date": "2026-09-01", "contextId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "more": [ "invoice" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/insights": { "get": { "tags": [ "Search, insights & deadlines" ], "summary": "Dashboard insights across growth, collections, cash flow, tax and expenses.", "operationId": "getApiInsights", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "actionLabel": { "type": "string" }, "actionRoute": { "type": "string" }, "isDismissed": { "type": "boolean" }, "generatedAt": { "type": "string" } } } }, "example": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "type": "standard", "title": "Karoo Fresh Holdings Ltd", "body": "Your invoice INV-0001 is attached.", "severity": "text", "category": "Office supplies", "actionLabel": "Karoo Fresh Holdings Ltd", "actionRoute": "text", "isDismissed": false, "generatedAt": "2026-09-01T09:15:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/insights/dismiss": { "post": { "tags": [ "Search, insights & deadlines" ], "summary": "Dismiss an insight so the carousel stops offering it.", "operationId": "postApiInsightsDismiss", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMrpForecastsResponse" }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "dismissed": { "type": "integer" } } }, "example": { "dismissed": 1 } } } }, "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.", "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/statutory/effective": { "get": { "tags": [ "SARS returns" ], "summary": "Every SA statutory figure the platform has published — PAYE brackets and rebates, the s6A medical credit, the UIF ceiling, the s11F cap, the travel rate per kilometre, the VAT rate, the company income tax rate and the SARS calendar. Published rows only: the app carries the compiled history in its binary and each registry overlays it, so this is what makes a rate published in the admin app reach an installed app without an update. No permission and no licence — SARS publishes all of it with no login, and gating it would leave two people in one business pricing invoices at two different VAT rates.", "operationId": "getApiStatutoryEffective", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiStatutoryEffectiveResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiStatutoryEffectiveResponseExample" } } } } }, "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/push/preferences": { "get": { "tags": [ "Push notifications" ], "summary": "My notifications: every push topic, whether the business allows it (Settings → Notifications) and whether this person wants it. A person can only narrow what the business allows.", "operationId": "getApiPushPreferences", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPushPreferencesResponse" }, "example": { "topics": [ { "topic": "push-assigned", "label": "Assigned to you", "description": "When a job, a workflow card or a trip is given to you", "allowedByBusiness": true, "enabled": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Push notifications" ], "summary": "Turn one push topic on or off for the signed-in person only. Answers with every topic, as GET does.", "operationId": "putApiPushPreferences", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string" }, "enabled": { "type": "boolean" } } }, "example": { "topic": "push-invoice-sent", "enabled": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiPushPreferencesResponse" }, "example": { "topics": [ { "topic": "push-invoice-sent", "label": "Invoice sent", "description": "When an invoice is delivered to a client", "allowedByBusiness": true, "enabled": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/push/status": { "get": { "tags": [ "Push notifications" ], "summary": "Whether this deployment can send at all, and which devices this user has registered. Both halves matter: a configured server with no device sends nothing, and a device on an unconfigured server receives nothing.", "operationId": "getApiPushStatus", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "serverConfigured": { "type": "boolean" }, "devices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string" }, "label": { "type": "string" }, "tokenHint": { "type": "string" }, "registeredAt": { "type": "string" }, "lastSeenAt": { "type": "string" } } } }, "reason": { "type": "string" } } }, "example": { "serverConfigured": true, "devices": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "platform": "text", "label": "Karoo Fresh Holdings Ltd", "tokenHint": "text", "registeredAt": "2026-09-01T09:15:00Z", "lastSeenAt": "2026-09-01T09:15:00Z" } ], "reason": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/push/tokens": { "post": { "tags": [ "Push notifications" ], "summary": "Register this install's FCM token. Idempotent — call it at every sign-in and on every token rotation; the same token for the same user just touches last_seen_at.", "operationId": "postApiPushTokens", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "platform": { "type": "string" }, "deviceId": { "type": "string" }, "label": { "type": "string" } } }, "example": { "token": "", "platform": "android", "deviceId": "b7e3a9d2-4c15-4f8e-9a60-2d1c7f5e8b34", "label": "Andy's phone" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPushTokensResponse" }, "example": { "status": "registered" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Push notifications" ], "summary": "Stop sending to this device. Both fields are optional: deviceId alone is enough when the token is no longer to hand, and neither retires every token this user holds. A sign-out does NOT need this — the server retires the device's tokens from /auth/logout.", "operationId": "deleteApiPushTokens", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "deviceId": { "type": "string" } } }, "example": { "token": "", "deviceId": "b7e3a9d2-4c15-4f8e-9a60-2d1c7f5e8b34" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiPushTokensResponse" }, "example": { "revoked": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/push/test": { "post": { "tags": [ "Push notifications" ], "summary": "Send a real push to the caller's own devices and report what happened — the only honest answer to \"is push working\". Goes through the same sender a payment notification does and deliberately ignores the topic switches, so a failure tells you it is broken rather than switched off.", "operationId": "postApiPushTest", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "attempted": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "retired": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "attempted": 1, "delivered": 1, "failed": 0, "retired": 1, "message": "Saved." } } } }, "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@capeunionmart.co.za", "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" }, "alsoCustomer": { "type": "boolean" }, "alsoSupplier": { "type": "boolean" } } }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "contactType": "customer", "name": "Karoo Fresh Holdings Ltd", "tradingName": "Karoo Fresh Holdings Ltd", "email": "billing@acme.co.za", "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, "alsoCustomer": false, "alsoSupplier": false } } } }, "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}": { "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.co.za", "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}/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.", "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}/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.co.za", "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.co.za", "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.co.za", "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.co.za", "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.co.za", "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": { "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" } } } }, "ageing": { "type": "object", "properties": { "current": { "type": "number" }, "days30": { "type": "number" }, "days60": { "type": "number" }, "days90": { "type": "number" }, "overdue": { "type": "number" } } }, "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 }, "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.", "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@capeunionmart.co.za", "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/aged-debtors": { "get": { "tags": [ "Contacts" ], "summary": "Aged debtors by bucket — current, 30, 60, 90 and over.", "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 } ], "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 }, "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/{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 five years the Tax Administration Act requires it to be kept. 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/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.", "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" } ], "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" } ], "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": { "contactId": { "type": "string" }, "companyId": { "type": "string" }, "costCentreId": { "type": "string" }, "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" }, "paymentGateways": { "type": "array", "items": { "type": "string" } }, "deliveryDate": { "type": "string", "format": "date" }, "customFields": { "$ref": "#/components/schemas/GetApiCrmLeadsResponseItemsItem" } } }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "companyId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "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": 45000.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, "paymentGateways": [ "payfast" ], "deliveryDate": "2026-09-01", "customFields": {} } } } }, "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.", "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": { "contactId": { "type": "string" }, "costCentreId": { "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" }, "paymentGateways": { "type": "array", "items": { "type": "string" } }, "deliveryDate": { "type": "string", "format": "date" }, "customFields": { "$ref": "#/components/schemas/GetApiCrmLeadsResponseItemsItem" } } }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "costCentreId": "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, "paymentGateways": [ "payfast" ], "deliveryDate": "2026-09-01", "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.", "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/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.", "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": { "$ref": "#/components/schemas/PostApiInvoicesByIdSendRequest" }, "example": { "channel": "email" } } } }, "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" } } }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "customerName": "Karoo Fresh Holdings Ltd", "currency": "ZAR", "available": 1.0, "amountDue": 10005.0, "applicable": 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": { "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": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "sentDate": { "type": "string", "format": "date" }, "channel": { "type": "string" }, "createdAt": { "type": "string" }, "status": { "type": "string" } } } }, "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" } } } }, "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", "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" } ], "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" ] } } } }, "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}/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}/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": { "docType": { "type": "string" }, "docTitle": { "type": "string" }, "number": { "type": "string" }, "date": { "type": "string", "format": "date" }, "due": { "type": "string", "format": "date" }, "status": { "type": "string" }, "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" }, "paymentMethod": { "type": "string" }, "paymentDate": { "type": "string", "format": "date" }, "domesticReverseCharge": { "type": "boolean" }, "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" } } } } } }, "example": { "docType": "invoice", "docTitle": "Karoo Fresh Holdings Ltd", "number": "INV-0001", "date": "2026-09-30", "due": "2026-10-31", "status": "sent", "currencyCode": "ZAR", "currencySymbol": "R", "sender": { "name": "Karoo Fresh Holdings Ltd", "address": "12 Long Street, Cape Town, 8001", "vatNumber": "4123456789", "email": "accounts@capeunionmart.co.za", "registrationNumber": "2021/123456/07" }, "client": { "name": "Karoo Fresh Holdings Ltd", "address": "12 Long Street, Cape Town, 8001", "vatNumber": "4123456789", "email": "accounts@capeunionmart.co.za", "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, "paymentMethod": "eft", "paymentDate": "2026-09-01", "domesticReverseCharge": false, "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" } ] } } } }, "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/number-leases": { "get": { "tags": [ "Invoicing & quotes" ], "summary": "Document-number leases this device holds. V213 built these so 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": { "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" } } }, "example": { "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" } } } }, "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": { "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" } } }, "example": { "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" } } } }, "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/PutApiReminderConfigsRequest" }, "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.", "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": { "$ref": "#/components/schemas/PutApiReminderConfigsRequest" }, "example": { "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/PutApiReminderConfigsRequest" }, "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 (V290) — 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” (QA-INVOICES F-49). 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" } } } }, "/pay/{linkId}": { "get": { "tags": [ "Payments & gateways" ], "summary": "The customer-facing pay page. Public by necessity — the person paying is not a Ledgr user — and guarded by the link id being an unguessable capability.", "operationId": "getPayByLinkId", "security": [], "parameters": [ { "name": "linkId", "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" } } } } } } }, "/pay/{linkId}/done": { "get": { "tags": [ "Payments & gateways" ], "summary": "Where PayFast returns the payer after a successful checkout.", "operationId": "getPayByLinkIdDone", "security": [], "parameters": [ { "name": "linkId", "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" } } } } } } }, "/pay/{linkId}/cancelled": { "get": { "tags": [ "Payments & gateways" ], "summary": "Where PayFast returns the payer after an abandoned checkout.", "operationId": "getPayByLinkIdCancelled", "security": [], "parameters": [ { "name": "linkId", "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" } } } } } } }, "/portal/invoice/{token}": { "get": { "tags": [ "Customer portal" ], "summary": "The customer's copy of a document, with pay, accept and decline where they apply.", "operationId": "getPortalInvoiceByToken", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "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": "html" }, { "name": "notice", "in": "query", "required": false, "schema": { "type": "string" }, "example": "done" } ], "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" } } } }, "/portal/invoice/{token}/pdf": { "get": { "tags": [ "Customer portal" ], "summary": "The same document as a PDF.", "operationId": "getPortalInvoiceByTokenPdf", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "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": "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" } } } }, "/portal/invoice/{token}/files/{fileId}": { "get": { "tags": [ "Customer portal" ], "summary": "A file the business sent with the document (QA-INVOICES F-49): a 302 to a freshly signed URL. Only a file ticked “Send with the document” — any other id answers 404 — and the token and its revocation are checked as the PDF's are. The page lists the ticked files; ?format=json carries them as files.", "operationId": "getPortalInvoiceByTokenFilesByFileId", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/portal/invoice/{token}/{decision}": { "post": { "tags": [ "Customer portal" ], "summary": "Accept or decline a quote online. A form post with a 303 redirect; JSON is accepted too. Records decided_at, the typed name as the signature and a decline reason — deliberately NO IP and no user agent, both of which are personal information needing a purpose and a retention position of their own.", "operationId": "postPortalInvoiceByTokenByDecision", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "decision", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "reason": { "type": "string" } } }, "example": { "name": "T. Nkosi", "reason": "Went with another supplier" } } } }, "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/portal/contact/{token}": { "get": { "tags": [ "Customer portal" ], "summary": "The customer's self-service view — their documents, their statement and their balance.", "operationId": "getPortalContactByToken", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "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": "html" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerName": { "type": "string" }, "supplierName": { "type": "string" }, "totalOutstanding": { "type": "number" }, "invoices": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string" }, "docType": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "status": { "type": "string" }, "total": { "type": "number" }, "amountDue": { "type": "number" }, "currency": { "type": "string" }, "invoiceToken": { "type": "string" } } } }, "asOf": { "type": "string" } } }, "example": { "customerName": "Karoo Fresh Holdings Ltd", "supplierName": "Karoo Fresh Holdings Ltd", "totalOutstanding": 10005.0, "invoices": [ { "number": "INV-0001", "docType": "invoice", "issueDate": "2026-09-01", "dueDate": "2026-10-01", "status": "sent", "total": 10005.0, "amountDue": 10005.0, "currency": "ZAR", "invoiceToken": "" } ], "asOf": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/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": { "$ref": "#/components/schemas/GetApiCrmLeadsResponse" }, "example": { "items": [ {} ], "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.co.za", "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@capeunionmart.co.za", "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/PostApiPushTokensResponse" }, "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" }, "stageId": { "type": "string" }, "expectedCloseDate": { "type": "string", "format": "date" } } }, "example": { "contactType": "customer", "createOpportunity": true, "opportunityName": "Karoo Fresh Holdings Ltd", "opportunityValue": 10005.0, "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" } ], "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, the same data the board renders.", "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": "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": "array", "items": { "$ref": "#/components/schemas/PostApiCrmOpportunitiesResponse" } }, "example": [ { "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" } } }, "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": { "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": { "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/PostApiPushTokensResponse" }, "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 — 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/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/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": { "name": { "type": "string" }, "sortOrder": { "type": "integer" }, "defaultProbability": { "type": "integer" }, "isWon": { "type": "boolean" }, "isLost": { "type": "boolean" }, "isActive": { "type": "boolean" } } }, "example": { "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/PostApiPushTokensResponse" }, "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": { "$ref": "#/components/schemas/GetApiCrmLeadsResponse" }, "example": { "items": [ {} ], "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/PutApiCrmActivitiesByIdResponse" }, "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/PostApiPushTokensResponse" }, "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/PutApiCrmActivitiesByIdResponse" }, "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@capeunionmart.co.za", "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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.co.za" } } } }, "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" } } } }, "/customer-portal": { "get": { "tags": [ "Customer ordering portal pages" ], "summary": "Where an old link (customer-portal#token) lands: it moves to the path form, and offers a box to paste the link or code when it cannot.", "operationId": "getCustomerPortal", "security": [], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Customer ordering portal pages" ], "summary": "The paste box: the whole link in either shape, or the bare code, answered with a 303 to the portal.", "operationId": "postCustomerPortal", "security": [], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } } } } }, "/customer-portal/{token}": { "get": { "tags": [ "Customer ordering portal pages" ], "summary": "Browse: the price list, searched by name, code or category (q) and paged fifty at a time (page), with an Add form on every row. added names the item just added, for the sentence that confirms it.", "operationId": "getCustomerPortalByToken", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "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": "disc" }, { "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": "2" }, { "name": "added", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "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" } } } }, "/customer-portal/{token}/basket": { "get": { "tags": [ "Customer ordering portal pages" ], "summary": "My basket, held by the server: quantities to change, totals, and Send this request. notice (updated, removed or emptied) and item say what the last action did; confirm=empty asks before emptying it.", "operationId": "getCustomerPortalByTokenBasket", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "notice", "in": "query", "required": false, "schema": { "type": "string" }, "example": "removed" }, { "name": "item", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "string" }, "example": "empty" } ], "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" } } }, "post": { "tags": [ "Customer ordering portal pages" ], "summary": "Update the basket's quantities, or send it as a request for a quote. A form post answered with a 303.", "operationId": "postCustomerPortalByTokenBasket", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/customer-portal/{token}/quotes": { "get": { "tags": [ "Customer ordering portal pages" ], "summary": "My quotes: every request and quote, converted ones included, each priced one linked to its document page to accept or decline. sent names the request just sent, for the thank-you.", "operationId": "getCustomerPortalByTokenQuotes", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sent", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "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" } } } }, "/customer-portal/{token}/basket/add": { "post": { "tags": [ "Customer ordering portal pages" ], "summary": "Add an item to the basket. A form post answered with a 303 back to the price list.", "operationId": "postCustomerPortalByTokenBasketAdd", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/customer-portal/{token}/basket/remove": { "post": { "tags": [ "Customer ordering portal pages" ], "summary": "Take one item out of the basket. A form post answered with a 303.", "operationId": "postCustomerPortalByTokenBasketRemove", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/customer-portal/{token}/basket/empty": { "post": { "tags": [ "Customer ordering portal pages" ], "summary": "Empty the basket, after asking. A form post answered with a 303.", "operationId": "postCustomerPortalByTokenBasketEmpty", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "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.", "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": { "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" }, "jobCardId": { "type": "string" }, "timeProjectId": { "type": "string" }, "rechargeable": { "type": "boolean" }, "vehicleId": { "type": "string" }, "tripId": { "type": "string" }, "costCentreId": { "type": "string" }, "receiptUrl": { "type": "string" }, "notes": { "type": "string" } } }, "example": { "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", "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", "receiptUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "notes": "Budget deferred to the next financial year." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiExpensesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiExpensesResponseExample" } } } } }, "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": "Makro", "category": "consumables", "timesSeen": 3, "lastUsedAt": "2026-09-01T08:00:00Z", "sentence": "Makro 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/PostApiPushTokensResponse" }, "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": { "date": { "type": "string", "format": "date" }, "costCentreId": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" }, "vatRate": { "type": "number" }, "vendor": { "type": "string" }, "supplierVatNumber": { "type": "string" }, "category": { "type": "string" }, "contactId": { "type": "string" }, "accountId": { "type": "string" }, "receiptUrl": { "type": "string" }, "notes": { "type": "string" }, "jobCardId": { "type": "string" }, "timeProjectId": { "type": "string" }, "rechargeable": { "type": "boolean" }, "vehicleId": { "type": "string" }, "tripId": { "type": "string" } } }, "example": { "date": "2026-09-01", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "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", "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": { "$ref": "#/components/schemas/PostApiExpensesResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiExpensesResponseExample" } } } } }, "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.", "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/PostApiBankRulesApplyRequest" }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "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" } } }, "example": { "code": "", "name": "Fuel and tolls", "color": "#0D47A1", "description": "Fuel, e-tolls and parking for business trips", "icon": "fuel", "sortOrder": 0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$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" } } } }, "/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@capeunionmart.co.za", "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@capeunionmart.co.za", "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@capeunionmart.co.za", "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}/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" } } }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "confirmDifferentAccount": false, "saveAccountNumber": 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" } } } }, "/inbound/email/{secret}": { "post": { "tags": [ "Expenses & claims" ], "summary": "Mailjet Parse API webhook: a forwarded supplier invoice becomes an inbox item. Registered only when LEDGR_INBOUND_EMAIL_SECRET is set.", "operationId": "postInboundEmailBySecret", "security": [], "parameters": [ { "name": "secret", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "integer" }, "note": { "type": "string" } } }, "example": { "accepted": 1, "note": "Budget deferred to the next financial year." } } } } } } }, "/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" } ], "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001" } ] } } }, "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" }, "costCentreId": { "type": "string" }, "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" } } }, "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", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "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" } ], "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "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" } } }, "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" } ], "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." } } } }, "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" }, "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" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PostApiBillsRequestLinesItem" } } } }, "example": { "exchangeRate": 18.5, "vendor": "Karoo Fresh Holdings Ltd", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "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", "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" } ] } } } }, "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.", "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": { "exchangeRate": { "type": "number" }, "clientId": { "type": "string" }, "bankAccountId": { "type": "string" } } }, "example": { "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" } ], "purchaseOrderId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "purchaseOrderNumber": "PO-0001" } } } }, "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@capeunionmart.co.za", "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" } } }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "tripDate": "2026-09-30", "origin": "sale", "destination": "accounts@capeunionmart.co.za", "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" } } } }, "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" } } }, "example": { "tripDate": "2026-09-01", "origin": "sale", "destination": "accounts@capeunionmart.co.za", "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 } } } }, "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@capeunionmart.co.za", "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" }, "days": { "type": "integer" }, "rateId": { "type": "string" }, "ratePerDay": { "type": "number" }, "notes": { "type": "string" } } }, "example": { "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employee": "Thandi Mokoena", "destination": "accounts@capeunionmart.co.za", "periodLabel": "2026-09", "days": 30, "rateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "ratePerDay": 15.0, "notes": "Budget deferred to the next financial year." } } } }, "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" }, "days": { "type": "integer" }, "ratePerDay": { "type": "number" }, "status": { "type": "string" }, "notes": { "type": "string" } } }, "example": { "rateId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employee": "Thandi Mokoena", "destination": "accounts@capeunionmart.co.za", "periodLabel": "2026-09", "days": 3, "ratePerDay": 1.0, "status": "sent", "notes": "Budget deferred to the next financial year." } } } }, "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.", "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/PostApiBankRulesApplyRequest" }, "example": { "bankAccountId": "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/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 or top up the float.", "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" } } }, "example": { "floatAmount": 1500.0 } } } }, "responses": { "204": { "description": "Done. No content." }, "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": { "clientId": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "category": { "type": "string" }, "receipt": { "type": "boolean" }, "notes": { "type": "string" } } }, "example": { "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." } } } }, "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": { "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "amount": { "type": "number" }, "category": { "type": "string" }, "receipt": { "type": "boolean" }, "notes": { "type": "string" } } }, "example": { "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." } } } }, "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. Moves the accrual to the bank (DR 2120 / CR 1350). 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" } } ], "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": { "type": "object", "properties": { "secondApprovalFrom": { "type": "number" } } }, "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 — 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/bills/payment-runs/{id}/bank-file": { "get": { "tags": [ "Expenses & claims" ], "summary": "The run's bank payment file (CSV: beneficiary name, account number, branch code, amount, reference). 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" } } ], "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/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/PostApiLedgerJournalsByIdReverseRequest" }, "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}/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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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@capeunionmart.co.za", "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@capeunionmart.co.za", "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 — 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/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": "sent", "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": "sent", "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": "sent", "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": "sent", "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": "sent", "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": { "name": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" }, "currentBalance": { "type": "number" }, "type": { "type": "string" }, "currency": { "type": "string" } } }, "example": { "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": "sent", "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": "sent", "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.", "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" }, "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": "TELKOM 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, "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" } } }, "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 } } } }, "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.", "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" } } } }, "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 } ] } } }, "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.", "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}/code": { "post": { "tags": [ "Banking & reconciliation" ], "summary": "Post a bank line to an account, or split it across several.", "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" } } }, "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" } } } }, "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" } } }, "example": { "ids": [ "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" ], "splits": [ { "accountCode": "6120", "vatRatePercent": 15.0, "percent": 100.0 } ], "memo": "Fuel for the Cape Town delivery run" } } } }, "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.", "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.", "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": "Uber and Bolt trips", "conditions": [ { "field": "description", "op": "contains", "value": "UBER|BOLT" } ], "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": "UBER|BOLT" } ], "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": { "$ref": "#/components/schemas/PostApiBankRulesApplyRequest" }, "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/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": "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/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" }, "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/{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.", "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/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.", "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" } } }, "example": { "name": "Stock write-offs and shrinkage", "description": "Consulting services — August 2026", "accountSubtype": "operating", "isActive": true } } } }, "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": { "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": { "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" } } } }, "/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" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLedgerJournalsByIdReverseRequest" }, "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/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" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLedgerPeriodsResponseExample" } } } } }, "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/PostApiPushTokensResponse" }, "example": { "status": "locked" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiLedgerPeriodsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiLedgerPeriodsResponseExample" } } } } }, "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.", "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": [] } ], "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": { "$ref": "#/components/schemas/PostApiLedgerCostCentresRequest" }, "example": { "code": "CPT", "name": "Cape Town branch", "description": "Consulting services — August 2026", "kind": "department", "parentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true } } } }, "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/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": { "$ref": "#/components/schemas/PostApiLedgerCostCentresRequest" }, "example": { "code": "CPT", "name": "Cape Town Depot", "description": "Consulting services — August 2026", "kind": "branch", "parentId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "isActive": true } } } }, "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" } ], "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" }, "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", "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" }, "amount": { "type": "number" }, "costCentreId": { "type": "string" }, "notes": { "type": "string" } } } } } }, "example": { "budgets": [ { "accountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodMonth": "2026-09", "amount": 45000.0, "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "notes": "Approved at the August board meeting" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "saved": { "type": "integer" } } }, "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" } ], "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 at the period-end rate and post the difference.", "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 — does the debtors control agree with the debtors ledger, does 1310 agree with the sum of open batch values.", "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.", "operationId": "getApiFxRates", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "base", "in": "query", "required": false, "schema": { "type": "string" }, "example": "ZAR" } ], "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, "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.", "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" }, "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" }, "clientId": { "type": "string" } } }, "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, "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", "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "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/{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" }, "method": { "type": "string" }, "ratePercent": { "type": "number" }, "serialNumber": { "type": "string" }, "location": { "type": "string" }, "costCentreId": { "type": "string" }, "notes": { "type": "string" } } }, "example": { "name": "Toyota Hilux (CA 123-456)", "description": "Consulting services — August 2026", "residualValue": 10005.0, "usefulLifeMonths": 1, "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." } } } }, "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" } } }, "example": { "disposalDate": "2026-09-30", "proceeds": 310000.0 } } } }, "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": [] } ], "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": "prior_year" } ], "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": "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": "prior_year" } ], "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" } ], "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/reports/trial-balance": { "get": { "tags": [ "Reports & analytics" ], "summary": "Trial balance. 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.", "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": "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" } } }, "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 } } } }, "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/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" } ], "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/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" } } }, "example": { "name": "Monthly management pack", "reportType": "income", "frequency": "monthly", "nextRun": "2026-09-01", "recipients": "finance@capeunionmart.co.za", "format": "pdf", "active": true, "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "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@capeunionmart.co.za", "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 — 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/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" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReportsAfsSettingsResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Reports & analytics" ], "summary": "Change the AFS settings.", "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" }, "averageEmployees": { "type": "integer" }, "beneficialInterestHolders": { "type": "integer" }, "internallyCompiled": { "type": "boolean" }, "ownerManaged": { "type": "boolean" } } }, "example": { "status": "sent", "rounding": "rand", "preparedBy": "Cameron & 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.", "averageEmployees": 1, "beneficialInterestHolders": 1, "internallyCompiled": true, "ownerManaged": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiReportsAfsSettingsResponse" }, "examples": { "default": { "$ref": "#/components/examples/GetApiReportsAfsSettingsResponseExample" } } } } }, "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.", "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": { "type": "object", "properties": { "statementKey": { "type": "string" }, "lineLabel": { "type": "string" }, "currentUnits": { "type": "integer" }, "priorUnits": { "type": "integer" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "accountType": { "type": "string" }, "currentUnits": { "type": "integer" }, "priorUnits": { "type": "integer" } } } }, "ties": { "type": "boolean" } } } }, "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 `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": { "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/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 `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": "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" }, "examples": { "default": { "$ref": "#/components/examples/GetApiSarsDocumentsIrp6ResponseExample" } } } } }, "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 ITR14. 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" } ], "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": "estimate" } ], "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": { "$ref": "#/components/schemas/PostApiSarsDocumentsDividendsResponse" } } } }, "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.", "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" } } } }, "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 } ], "clientId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsDocumentsDividendsResponse" }, "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" } } } }, "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.", "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/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/vat201": { "get": { "tags": [ "SARS returns" ], "summary": "The computed VAT201 boxes, as the screen renders them.", "operationId": "getApiSarsVat201", "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": "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" }, "outputVat": { "type": "number" }, "inputVat": { "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, "outputVat": 1305.0, "inputVat": 1305.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/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.", "operationId": "postApiSarsVat201Submit", "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": { "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" } } }, "example": { "periodStart": "2026-07-01", "periodEnd": "2026-08-31" } } } }, "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/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" } } }, "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 } } } }, "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": { "type": "object", "properties": { "year": { "type": "integer" } } }, "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.", "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": "1" }, { "name": "basis", "in": "query", "required": false, "schema": { "type": "string" }, "example": "estimate" } ], "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.", "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" } } }, "example": { "year": 2027, "period": 1, "basis": "invoice" } } } }, "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-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/PostApiSarsIrp6SubmitResponse" } }, "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" } ] } } }, "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/PostApiSarsIrp6SubmitResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsIrp6SubmitResponseExample" } } } } }, "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/PostApiSarsIrp6SubmitResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsIrp6SubmitResponseExample" } } } } }, "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/PostApiSarsIrp6SubmitResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsIrp6SubmitResponseExample" } } } } }, "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.", "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" } } ], "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-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/sars/transmissions": { "get": { "tags": [ "SARS returns" ], "summary": "ISV direct filing. DORMANT — the whole tree is unregistered unless LEDGR_SARS_DIRECT_FILING is on, so these are a plain 404 by default and must never be surfaced in a client.", "operationId": "getApiSarsTransmissions", "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": { "transmissions": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSarsTransmissionsResponseTransmissionsItem" } }, "isv": { "$ref": "#/components/schemas/GetApiSarsTransmissionsIsvResponse" } } }, "example": { "transmissions": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "submissionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "taxType": "VAT201", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "channel": "email", "status": "sent", "statusLabel": "Karoo Fresh Holdings Ltd", "testSubmission": true, "sarsReference": "INV-0001", "sarsStatusRaw": "text", "lastError": "text", "attempts": 1, "sentAt": "2026-09-01T09:15:00Z", "acknowledgedAt": "2026-09-01T09:15:00Z", "nextAttemptAt": "2026-09-01T09:15:00Z", "envelopeFormat": "CSV", "envelopeBytes": 1, "createdAt": "2026-09-01T09:15:00Z" } ], "isv": { "configured": true, "missingConfiguration": [ "text" ], "production": false, "baseUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "isvId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supportedTaxTypes": [ "standard" ], "certificateSubject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "certificateExpiresAt": "2026-09-01T09:15:00Z", "certificateDaysRemaining": 30, "certificateExpired": false, "summary": "Consulting services — August 2026" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/transmissions/isv": { "get": { "tags": [ "SARS returns" ], "summary": "ISV registration status. Dormant, as above.", "operationId": "getApiSarsTransmissionsIsv", "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": { "$ref": "#/components/schemas/GetApiSarsTransmissionsIsvResponse" }, "example": { "configured": true, "missingConfiguration": [ "text" ], "production": false, "baseUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "isvId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "supportedTaxTypes": [ "standard" ], "certificateSubject": "Invoice INV-0001 from Karoo Fresh Holdings Ltd", "certificateExpiresAt": "2026-09-01T09:15:00Z", "certificateDaysRemaining": 30, "certificateExpired": false, "summary": "Consulting services — August 2026" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/transmissions/preview/{submissionId}": { "get": { "tags": [ "SARS returns" ], "summary": "Preview the envelope that would be transmitted. Dormant.", "operationId": "getApiSarsTransmissionsPreviewBySubmissionId", "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": "submissionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "submissionId": { "type": "string" }, "taxType": { "type": "string" }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "type": "string", "format": "date" }, "correlationId": { "type": "string" }, "xml": { "type": "string" }, "unmappedFields": { "type": "array", "items": { "type": "string" } }, "blockingIssues": { "type": "array", "items": { "type": "string" } }, "filable": { "type": "boolean" }, "canTransmit": { "type": "boolean" }, "testSubmission": { "type": "boolean" } } }, "example": { "submissionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "taxType": "VAT201", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "correlationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "xml": "text", "unmappedFields": [ "text" ], "blockingIssues": [ "The control account and the age analysis differ by R0.00." ], "filable": true, "canTransmit": true, "testSubmission": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/transmissions/{submissionId}": { "post": { "tags": [ "SARS returns" ], "summary": "Transmit a submission. Dormant.", "operationId": "postApiSarsTransmissionsBySubmissionId", "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": "submissionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiSarsTransmissionsByIdPollResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsTransmissionsByIdPollResponseExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/transmissions/{id}/detail": { "get": { "tags": [ "SARS returns" ], "summary": "A transmission's state. Dormant.", "operationId": "getApiSarsTransmissionsByIdDetail", "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": { "type": "object", "properties": { "transmission": { "$ref": "#/components/schemas/GetApiSarsTransmissionsResponseTransmissionsItem" }, "events": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer" }, "kind": { "type": "string" }, "status": { "type": "string" }, "httpStatus": { "type": "integer" }, "detail": { "type": "string" }, "durationMs": { "type": "integer" }, "createdAt": { "type": "string" } } } }, "envelope": { "type": "string" } } }, "example": { "transmission": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "submissionId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "taxType": "VAT201", "periodStart": "2026-09-01", "periodEnd": "2026-09-30", "channel": "email", "status": "sent", "statusLabel": "Karoo Fresh Holdings Ltd", "testSubmission": true, "sarsReference": "INV-0001", "sarsStatusRaw": "text", "lastError": "text", "attempts": 1, "sentAt": "2026-09-01T09:15:00Z", "acknowledgedAt": "2026-09-01T09:15:00Z", "nextAttemptAt": "2026-09-01T09:15:00Z", "envelopeFormat": "CSV", "envelopeBytes": 1, "createdAt": "2026-09-01T09:15:00Z" }, "events": [ { "attempt": 1, "kind": "standard", "status": "sent", "httpStatus": 1, "detail": "Saved.", "durationMs": 1, "createdAt": "2026-09-01T09:15:00Z" } ], "envelope": "text" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sars/transmissions/{id}/envelope": { "get": { "tags": [ "SARS returns" ], "summary": "The transmitted envelope. Dormant.", "operationId": "getApiSarsTransmissionsByIdEnvelope", "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 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/transmissions/{id}/poll": { "post": { "tags": [ "SARS returns" ], "summary": "Poll SARS for an outcome. Dormant.", "operationId": "postApiSarsTransmissionsByIdPoll", "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": { "$ref": "#/components/schemas/PostApiSarsTransmissionsByIdPollResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiSarsTransmissionsByIdPollResponseExample" } } } } }, "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": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "firstName": "Karoo Fresh Holdings Ltd", "lastName": "Karoo Fresh Holdings Ltd", "idNumber": "INV-0001", "dateOfBirth": "1988-04-12", "employmentType": "standard", "startDate": "2026-09-01", "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@capeunionmart.co.za", "phone": "+27 82 555 0143", "bankName": "FNB", "bankAccountNumber": "62012345678", "bankBranchCode": "250655", "taxNumber": "INV-0001", "uifLiable": true, "basicSalary": 1.0, "travelAllowance": 1.0, "pensionContribution": 1.0, "medicalAidContribution": 1.0, "medicalAidMembers": 1, "travelInclusionRate": 15.0, "leaveBalances": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leaveType": "annual", "balanceDays": 10005.0, "takenDays": 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": [ "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" }, "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" }, "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" }, "natureOfPerson": { "type": "string" }, "passportNumber": { "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" } } }, "example": { "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "firstName": "Andy", "lastName": "Cameron", "idNumber": "8001015800087", "dateOfBirth": "1988-04-12", "employmentType": "PERMANENT", "startDate": "2026-03-01", "endDate": "2026-09-30", "jobTitle": "Karoo Fresh Holdings Ltd", "department": "Sales", "costCentreId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "email": "accounts@capeunionmart.co.za", "phone": "+27 82 555 0143", "bankAccountNumber": "62012345678", "bankName": "FNB", "bankBranchCode": "250655", "bankAccountType": "current", "taxNumber": "0000012345", "uifLiable": true, "payFrequency": "MONTHLY", "basicSalary": 45000.0, "travelAllowance": 1.0, "pensionContribution": 1.0, "medicalAidContribution": 1.0, "medicalAidMembers": 1, "travelInclusionRate": 15.0, "natureOfPerson": "A", "passportNumber": "INV-0001", "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 } } } }, "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": { "type": "object", "properties": { "id": { "type": "string" }, "employeeNumber": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "idNumber": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date" }, "employmentType": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "terminationReason": { "type": "string" }, "jobTitle": { "type": "string" }, "department": { "type": "string" }, "costCentreId": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "bankName": { "type": "string" }, "bankAccountNumber": { "type": "string" }, "bankBranchCode": { "type": "string" }, "taxNumber": { "type": "string" }, "uifLiable": { "type": "boolean" }, "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" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeNumber": "INV-0001", "firstName": "Karoo Fresh Holdings Ltd", "lastName": "Karoo Fresh Holdings Ltd", "idNumber": "INV-0001", "dateOfBirth": "1988-04-12", "employmentType": "standard", "startDate": "2026-09-01", "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@capeunionmart.co.za", "phone": "+27 82 555 0143", "bankName": "FNB", "bankAccountNumber": "62012345678", "bankBranchCode": "250655", "taxNumber": "INV-0001", "uifLiable": true, "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 } ], "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": [ "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": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "employmentType": { "type": "string" }, "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" }, "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" }, "natureOfPerson": { "type": "string" }, "passportNumber": { "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" } } }, "example": { "firstName": "Thandi", "lastName": "Mokoena", "employmentType": "standard", "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@capeunionmart.co.za", "phone": "+27 82 555 0143", "bankAccountNumber": "62012345678", "bankName": "FNB", "bankBranchCode": "250655", "bankAccountType": "standard", "taxNumber": "INV-0001", "uifLiable": true, "payFrequency": "MONTHLY", "basicSalary": 48000.0, "travelAllowance": 1.0, "pensionContribution": 1.0, "medicalAidContribution": 1.0, "medicalAidMembers": 1, "travelInclusionRate": 15.0, "natureOfPerson": "A", "passportNumber": "INV-0001", "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 } } } }, "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.", "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" } ], "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.", "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": { "$ref": "#/components/schemas/GetApiPayrollIrp5ResponseItem" }, "example": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "employeeNumber": "INV-0001", "taxNumber": "INV-0001", "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, "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.", "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}/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/{id}/approve": { "post": { "tags": [ "Payroll" ], "summary": "Approve the run and lock the payslips.", "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.", "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" } } ], "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": { "$ref": "#/components/schemas/PostApiBankRulesApplyRequest" }, "example": { "bankAccountId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "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. 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": { "type": "object", "properties": { "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03": { "type": "number" } } } } }, "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 } } } } }, "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": { "$ref": "#/components/schemas/PostApiInvoicesByIdSendRequest" }, "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.", "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": { "$ref": "#/components/schemas/GetApiPayrollIrp5ResponseItem" } }, "example": [ { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "employeeName": "Thandi Mokoena", "employeeNumber": "INV-0001", "taxNumber": "INV-0001", "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, "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/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.", "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 — 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/easyfile/import-file": { "get": { "tags": [ "Payroll" ], "summary": "The e@syFile Employer import file itself.", "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" } ], "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@capeunionmart.co.za", "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@capeunionmart.co.za", "contactPhone": "+27 82 555 0143", "remittanceEmail": "accounts@capeunionmart.co.za", "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@capeunionmart.co.za", "contactPhone": "+27 82 555 0143", "remittanceEmail": "contributions@momentum.co.za", "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@capeunionmart.co.za", "contactPhone": "+27 82 555 0143", "remittanceEmail": "accounts@capeunionmart.co.za", "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": "text", "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." } ] } } }, "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" }, "example": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "beneficiaryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "memberReference": "MOM-4471", "calculation": "FIXED", "employeeAmount": 1500.0, "employerAmount": 1500.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." } } } }, "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" }, "example": { "employeeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "beneficiaryId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "memberReference": "INV-0001", "calculation": "FIXED", "employeeAmount": 1800.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." } } } }, "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": { "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": "number" } } } } } }, "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, "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. The engine and the tables existed from V211; nothing could write a row without a SQL client until this route.", "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, "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, "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" } } }, "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 } } } }, "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 }, "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" }, "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, "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/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}/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. Not an ACB/BankServ fixed-width file: that layout needs a bank-assigned user code and nominated account Ledgr holds no field for.", "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/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" } } }, "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@capeunionmart.co.za", "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" } } } } }, "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/PostApiPushTokensResponse" }, "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/GetAuthSsoProvidersResponseItem" } }, "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/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/PostApiPushTokensResponse" }, "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/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.", "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": [] } ], "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" } } } }, "/portal/employee/{token}": { "get": { "tags": [ "Employee self-service portal" ], "summary": "The employee's own view — payslips, certificates, leave and their details.", "operationId": "getPortalEmployeeByToken", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "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": "html" }, { "name": "sent", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": "true" } ], "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" } } } }, "/portal/employee/{token}/payslips/{payslipId}": { "get": { "tags": [ "Employee self-service portal" ], "summary": "One payslip.", "operationId": "getPortalEmployeeByTokenPayslipsByPayslipId", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "payslipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "periodLabel": { "type": "string" }, "payDate": { "type": "string", "format": "date" }, "status": { "type": "string" }, "earnings": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "deductions": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "employerContributions": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "grossSalary": { "type": "number" }, "totalDeductions": { "type": "number" }, "netPay": { "type": "number" }, "ytdGross": { "type": "number" }, "ytdPaye": { "type": "number" }, "taxableBenefits": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiReportsCashFlowResponseFinancingItem" } }, "catchUpNotice": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "periodLabel": "2026-09", "payDate": "2026-09-01", "status": "sent", "earnings": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "deductions": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "employerContributions": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "grossSalary": 1.0, "totalDeductions": 10005.0, "netPay": 8700.0, "ytdGross": 1.0, "ytdPaye": 1.0, "taxableBenefits": [ { "name": "Karoo Fresh Holdings Ltd", "amount": 10005.0 } ], "catchUpNotice": "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" } } } }, "/portal/employee/{token}/payslips/{payslipId}/pdf": { "get": { "tags": [ "Employee self-service portal" ], "summary": "That payslip as a PDF.", "operationId": "getPortalEmployeeByTokenPayslipsByPayslipIdPdf", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "payslipId", "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" } } } }, "/portal/employee/{token}/certificates": { "get": { "tags": [ "Employee self-service portal" ], "summary": "The employee's IRP5/IT3(a) certificates.", "operationId": "getPortalEmployeeByTokenCertificates", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "taxYear": { "type": "string" }, "taxYearEnd": { "type": "integer" }, "certificateNumber": { "type": "string" }, "grossRemuneration": { "type": "number" }, "payeDeducted": { "type": "number" }, "uifTotal": { "type": "number" }, "pensionTotal": { "type": "number" }, "medicalTotal": { "type": "number" }, "medicalTaxCredit": { "type": "number" }, "totalTaxSdlUif": { "type": "number" }, "monthsWorked": { "type": "integer" }, "takeOnIncluded": { "type": "boolean" } } } }, "example": [ { "taxYear": "2027", "taxYearEnd": 1, "certificateNumber": "INV-0001", "grossRemuneration": 1.0, "payeDeducted": 1.0, "uifTotal": 10005.0, "pensionTotal": 10005.0, "medicalTotal": 10005.0, "medicalTaxCredit": 1305.0, "totalTaxSdlUif": 1305.0, "monthsWorked": 1, "takeOnIncluded": false } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/portal/employee/{token}/certificates/{taxYear}/pdf": { "get": { "tags": [ "Employee self-service portal" ], "summary": "One certificate as a PDF.", "operationId": "getPortalEmployeeByTokenCertificatesByTaxYearPdf", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "taxYear", "in": "path", "required": true, "schema": { "type": "string" } } ], "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" } } } }, "/portal/employee/{token}/leave": { "post": { "tags": [ "Employee self-service portal" ], "summary": "Request leave, as JSON.", "operationId": "postPortalEmployeeByTokenLeave", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "fromDate": { "type": "string", "format": "date" }, "toDate": { "type": "string", "format": "date" } } }, "example": { "type": "annual", "fromDate": "2026-12-16", "toDate": "2026-12-24" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "leaveType": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "daysRequested": { "type": "number" }, "status": { "type": "string" }, "reason": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "leaveType": "annual", "startDate": "2026-09-01", "endDate": "2026-09-30", "daysRequested": 1.0, "status": "sent", "reason": "Budget deferred to the next financial year." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/portal/employee/{token}/forms/leave": { "post": { "tags": [ "Employee self-service portal" ], "summary": "The same request as a plain form post. The page sends Referrer-Policy: no-referrer to keep its own token out of a third party's logs, which is why these posts sit outside the CORS gate.", "operationId": "postPortalEmployeeByTokenFormsLeave", "security": [ { "bearerAuth": [] } ], "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" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/portal/employee/{token}/forms/leave/{id}/withdraw": { "post": { "tags": [ "Employee self-service portal" ], "summary": "Withdraw a leave request the employee sent by mistake. Only a request still awaiting a decision may be withdrawn — the rule is EssSubmission.employeeMayWithdraw, which the page reads too, so a Withdraw button cannot appear on a row this refuses. An APPROVED request is deliberately not withdrawable here: the days are already off the balance and releasing them is the employer's own cancel. The refusal says so and says who to ask.", "operationId": "postPortalEmployeeByTokenFormsLeaveByIdWithdraw", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "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" } } } }, "/portal/employee/{token}/change-request": { "post": { "tags": [ "Employee self-service portal" ], "summary": "Ask for a detail change — address, bank account, contact number — as JSON. It is a request, not a write.", "operationId": "postPortalEmployeeByTokenChangeRequest", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "field": { "type": "string" }, "newValue": { "type": "string" } } }, "example": { "field": "bankAccountNumber", "newValue": "62811111111" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "requestType": { "type": "string" }, "typeLabel": { "type": "string" }, "status": { "type": "string" }, "newValue": { "type": "string" }, "employeeNote": { "type": "string" }, "reviewerNote": { "type": "string" }, "createdAt": { "type": "string" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "requestType": "standard", "typeLabel": "Standard", "status": "sent", "newValue": "text", "employeeNote": "Budget deferred to the next financial year.", "reviewerNote": "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" } } } }, "/portal/employee/{token}/forms/change": { "post": { "tags": [ "Employee self-service portal" ], "summary": "The same change request as a form post.", "operationId": "postPortalEmployeeByTokenFormsChange", "security": [ { "bearerAuth": [] } ], "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" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/portal/employee/{token}/forms/document": { "post": { "tags": [ "Employee self-service portal" ], "summary": "The employee files a document from the portal — multipart, no JavaScript. Lands unverified: an upload is not verified by arriving, for the same reason a change of banking details is a request. A bank confirmation letter is refused here on purpose.", "operationId": "postPortalEmployeeByTokenFormsDocument", "security": [ { "bearerAuth": [] } ], "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" } } } }, "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": { "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": { "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/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": { "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": { "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 (QA-INVENTORY G-05): 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 (QA-INVENTORY G-07): 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" } } }, "example": { "code": "CT-001", "name": "Karoo Fresh Holdings Ltd", "color": "#0D47A1", "icon": "inventory", "description": "Consulting services — August 2026", "sortOrder": 1 } } } }, "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": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer" }, "isActive": { "type": "boolean" } } }, "example": { "code": "CT-001", "name": "Workshop consumables", "color": "#0D47A1", "icon": "inventory", "description": "Consulting services — August 2026", "sortOrder": 1, "isActive": true } } } }, "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": { "productId": { "type": "string" }, "variantId": { "type": "null" }, "unitPrice": { "type": "number" } } }, "example": { "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" } } }, "example": { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "name": "Durban Showroom", "address": "12 Long Street, Cape Town, 8001", "type": "standard" } } } }, "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" } } }, "example": { "name": "Durban Showroom (Umhlanga)", "address": "12 Long Street, Cape Town, 8001", "type": "standard", "isActive": true } } } }, "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/GetApiCrmLeadsResponseItemsItem" }, "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/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" }, "locationId": { "type": "string" } } }, "example": { "productId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "deltaQty": 2.0, "reason": "Captured during the August review", "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/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/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.", "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" } } } }, "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" ] } } } }, "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/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/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" } } }, "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" } } } }, "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" } } }, "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." } } } }, "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/PostApiPushTokensResponse" }, "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" } } }, "example": { "status": "awaiting_parts", "note": "Budget deferred to the next financial year." } } } }, "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" } } }, "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." } } } }, "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" } } }, "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." } } } }, "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": { "locationId": { "type": "string" } } }, "example": { "locationId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "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/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@capeunionmart.co.za", "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@capeunionmart.co.za", "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" } } }, "example": { "signOffName": "Karoo Fresh Holdings Ltd", "signOffRole": "Accountant", "signOffSignature": "", "signOffNotes": "Budget deferred to the next financial year.", "complete": true } } } }, "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. 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" } } }, "example": { "override": false, "issueDate": "2026-08-26", "paymentTermsDays": 30, "vatRate": 15.0, "summariseLabour": false } } } }, "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" } } }, "example": { "invoiceId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "invoiceNumber": "INV-0001", "linesCreated": 1, "total": 10005.0, "currency": "ZAR" } } } }, "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/{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/PostStatusSubscribeRequest" }, "example": { "email": "accounts@coastalcold.co.za" } } } }, "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/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" } ], "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." } } } }, "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." } } } }, "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/PostApiPushTokensResponse" }, "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. There was no edit route at all until V261, so a mis-typed 8 hours could only 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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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": { "$ref": "#/components/schemas/PostApiTimeTrackingProjectsResponse" } }, "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 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Time tracking" ], "summary": "Create a project.", "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" } } }, "example": { "name": "Mobile app phase 2", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hourlyRate": 850.0, "billable": true, "budgetHours": 320.0, "budgetAmount": 272000.0 } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiTimeTrackingProjectsResponse" }, "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 } } } }, "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" }, "clearBudgetHours": { "type": "boolean" }, "clearBudgetAmount": { "type": "boolean" }, "clearContactId": { "type": "boolean" } } }, "example": { "name": "Karoo Fresh Holdings Ltd", "contactId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "hourlyRate": 900.0, "billable": true, "active": true, "budgetHours": 3.0, "budgetAmount": 10005.0, "clearBudgetHours": false, "clearBudgetAmount": false, "clearContactId": 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" } } } }, "/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/PostApiPushTokensResponse" }, "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 } ] } } }, "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 empty it.", "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" } } }, "example": { "defaultChargeRate": 950.0, "defaultCostRate": 420.0, "clearChargeRate": false, "clearCostRate": 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 } } } }, "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@capeunionmart.co.za" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/workflows/link-options": { "get": { "tags": [ "Workflows" ], "summary": "Matters and customers a board or a card can be linked to, as {id, name} pairs. 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" } } } }, "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" } ] } } } }, "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" }, "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", "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": { "$ref": "#/components/schemas/PostApiWorkflowsItemsResponse" }, "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" } } } }, "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" }, "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" } ] } } } }, "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" } } }, "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" } } } }, "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}/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 (V237). 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/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 (QA-BOM G-17). 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 (QA-BOM G-14) 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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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 (QA-BOM G-14). `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 (QA-BOM G-17).", "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 V289 refuses 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": { "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/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/PostApiPushTokensResponse" }, "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": [] } ], "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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 (QA G-01): 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 (QA G-08); 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 (QA G-08): `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 (QA G-08). 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": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } } } }, "example": { "items": [] } } } }, "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 (QA G-08). `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 (QA G-08): `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 (QA G-08). 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 (QA G-08): `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 (QA G-14). 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 (QA G-14). 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 (QA G-09). `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 (QA G-09): 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 (QA G-21): 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 (QA G-17). `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 (QA G-17). 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 (QA G-07): 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 (QA G-10), 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 (QA G-10). `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 (QA G-10): 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 (QA G-10): 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" } ], "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 (QA G-18) — 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/PostApiPushTokensResponse" }, "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": { "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": { "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) — QA G-16: 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": { "documentId": { "type": "string" }, "productId": { "type": "string" } } }, "example": { "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/{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 (QA G-05): `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": { "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": { "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 (QA G-20): 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 (QA G-12) — `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 (QA G-13), 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. `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" } ], "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/GetApiCrmLeadsResponseItemsItem" }, "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" } ], "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 (QA G-03) — 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 (QA G-22): 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/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 (QA G-02), 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 (QA G-02), 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": { "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" } } } }, "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 — 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/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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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.", "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "example": { "status": "active" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPushTokensResponse" }, "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@capeunionmart.co.za", "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 — 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/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": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" }, "contactId": { "type": "string" }, "vendorRowCount": { "type": "integer" }, "applicantEmailed": { "type": "boolean" } } }, "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@capeunionmart.co.za", "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@capeunionmart.co.za", "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/PostApiPushTokensResponse" }, "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/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/PostApiPushTokensResponse" }, "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.co.za", "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" } } } }, "/supplier-portal": { "get": { "tags": [ "Supplier portal pages" ], "summary": "Forwards an old /supplier-portal# link into the path form with one hashed script, and offers a box to paste the link into.", "operationId": "getSupplierPortal", "security": [], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Supplier portal pages" ], "summary": "The paste box: the whole link in either shape, a link broken across lines, or the bare code. A 303 to /supplier-portal/{token}.", "operationId": "postSupplierPortal", "security": [], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } } } } }, "/supplier-portal/{token}": { "get": { "tags": [ "Supplier portal pages" ], "summary": "The supplier's home page: what waits for them, their figures, and their link's expiry.", "operationId": "getSupplierPortalByToken", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "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" } } } }, "/supplier-portal/{token}/orders": { "get": { "tags": [ "Supplier portal pages" ], "summary": "Their purchase orders, newest first, with value and where each stands.", "operationId": "getSupplierPortalByTokenOrders", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "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" } } } }, "/supplier-portal/{token}/orders/{id}": { "get": { "tags": [ "Supplier portal pages" ], "summary": "One order: its lines, the answer form, the invoices sent against it, and the despatch control.", "operationId": "getSupplierPortalByTokenOrdersById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "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" } } } }, "/supplier-portal/{token}/orders/{id}/acknowledge": { "post": { "tags": [ "Supplier portal pages" ], "summary": "Confirm an order, decline it, or offer another delivery date. A form post answered with a 303; the buyer is told.", "operationId": "postSupplierPortalByTokenOrdersByIdAcknowledge", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-portal/{token}/orders/{id}/invoice": { "get": { "tags": [ "Supplier portal pages" ], "summary": "The invoice form for an order, filled in with what was delivered and not yet invoiced.", "operationId": "getSupplierPortalByTokenOrdersByIdInvoice", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "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" } } }, "post": { "tags": [ "Supplier portal pages" ], "summary": "Send an invoice against the order: a draft bill, de-duplicated on the invoice number, figures read the South African way.", "operationId": "postSupplierPortalByTokenOrdersByIdInvoice", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-portal/{token}/orders/{id}/despatch": { "get": { "tags": [ "Supplier portal pages" ], "summary": "The despatch advice form: what is still to send on each line.", "operationId": "getSupplierPortalByTokenOrdersByIdDespatch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "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" } } }, "post": { "tags": [ "Supplier portal pages" ], "summary": "Tell the buyer goods have left. Moves no stock; a goods receipt later marks it delivered.", "operationId": "postSupplierPortalByTokenOrdersByIdDespatch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-portal/{token}/invoices": { "get": { "tags": [ "Supplier portal pages" ], "summary": "The invoices this supplier has sent, with where each stands and what the three-way match found.", "operationId": "getSupplierPortalByTokenInvoices", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "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" } } } }, "/supplier-portal/{token}/invoices/new": { "get": { "tags": [ "Supplier portal pages" ], "summary": "The form for an invoice with no purchase order.", "operationId": "getSupplierPortalByTokenInvoicesNew", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "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" } } }, "post": { "tags": [ "Supplier portal pages" ], "summary": "Send an invoice with no purchase order.", "operationId": "postSupplierPortalByTokenInvoicesNew", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-portal/{token}/invoices/{id}/withdraw": { "get": { "tags": [ "Supplier portal pages" ], "summary": "Asks before an invoice the buyer has not accepted is withdrawn.", "operationId": "getSupplierPortalByTokenInvoicesByIdWithdraw", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "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" } } }, "post": { "tags": [ "Supplier portal pages" ], "summary": "Withdraw an invoice the buyer has not accepted.", "operationId": "postSupplierPortalByTokenInvoicesByIdWithdraw", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-portal/{token}/rfqs": { "get": { "tags": [ "Supplier portal pages" ], "summary": "Requests to quote, open ones apart from closed ones.", "operationId": "getSupplierPortalByTokenRfqs", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "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" } } } }, "/supplier-portal/{token}/rfqs/{id}": { "get": { "tags": [ "Supplier portal pages" ], "summary": "One request to quote, with the quote form while it is open.", "operationId": "getSupplierPortalByTokenRfqsById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "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" } } } }, "/supplier-portal/{token}/rfqs/{id}/quote": { "post": { "tags": [ "Supplier portal pages" ], "summary": "Send or replace a quote. Every priced line is worth something and its validity has not passed.", "operationId": "postSupplierPortalByTokenRfqsByIdQuote", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-portal/{token}/offers": { "get": { "tags": [ "Supplier portal pages" ], "summary": "Prices the supplier offered without being asked, with revise and withdraw.", "operationId": "getSupplierPortalByTokenOffers", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "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" } } }, "post": { "tags": [ "Supplier portal pages" ], "summary": "Send an offer, or a revision of one; one replay key per form drawn.", "operationId": "postSupplierPortalByTokenOffers", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-portal/{token}/offers/new": { "get": { "tags": [ "Supplier portal pages" ], "summary": "The offer form, or the revision form with ?revise={id}.", "operationId": "getSupplierPortalByTokenOffersNew", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "revise", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "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" } } } }, "/supplier-portal/{token}/offers/{id}/withdraw": { "get": { "tags": [ "Supplier portal pages" ], "summary": "Asks before an offer is withdrawn.", "operationId": "getSupplierPortalByTokenOffersByIdWithdraw", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "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" } } }, "post": { "tags": [ "Supplier portal pages" ], "summary": "Withdraw an offer.", "operationId": "postSupplierPortalByTokenOffersByIdWithdraw", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-portal/{token}/catalogue": { "get": { "tags": [ "Supplier portal pages" ], "summary": "The supplier's price list for this buyer.", "operationId": "getSupplierPortalByTokenCatalogue", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "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" } } }, "post": { "tags": [ "Supplier portal pages" ], "summary": "Add or change a price-list item and its volume breaks.", "operationId": "postSupplierPortalByTokenCatalogue", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-portal/{token}/catalogue/new": { "get": { "tags": [ "Supplier portal pages" ], "summary": "The form for a new price-list item.", "operationId": "getSupplierPortalByTokenCatalogueNew", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "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" } } } }, "/supplier-portal/{token}/catalogue/{id}/edit": { "get": { "tags": [ "Supplier portal pages" ], "summary": "The form for changing a price-list item.", "operationId": "getSupplierPortalByTokenCatalogueByIdEdit", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "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" } } } }, "/supplier-portal/{token}/catalogue/{id}/withdraw": { "get": { "tags": [ "Supplier portal pages" ], "summary": "Asks before an item stops being offered.", "operationId": "getSupplierPortalByTokenCatalogueByIdWithdraw", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "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" } } }, "post": { "tags": [ "Supplier portal pages" ], "summary": "Stop offering an item.", "operationId": "postSupplierPortalByTokenCatalogueByIdWithdraw", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-portal/{token}/documents": { "get": { "tags": [ "Supplier portal pages" ], "summary": "Compliance documents on file, what is due for renewal, and what the buyer still needs.", "operationId": "getSupplierPortalByTokenDocuments", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "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" } } }, "post": { "tags": [ "Supplier portal pages" ], "summary": "Send a document: the file and its facts in one multipart form, the file typed by its bytes.", "operationId": "postSupplierPortalByTokenDocuments", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-portal/{token}/documents/send": { "get": { "tags": [ "Supplier portal pages" ], "summary": "The form for one kind of document, ?kind=bbbee_certificate and so on.", "operationId": "getSupplierPortalByTokenDocumentsSend", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "example": "bbbee_certificate" } ], "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" } } } }, "/supplier-portal/{token}/payments": { "get": { "tags": [ "Supplier portal pages" ], "summary": "What the buyer owes, the statement, the scorecard and the despatches the supplier sent.", "operationId": "getSupplierPortalByTokenPayments", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "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" } } } }, "/supplier-registration": { "get": { "tags": [ "Supplier portal pages" ], "summary": "Forwards an old /supplier-registration# link into the path form, and offers a box to paste the link into.", "operationId": "getSupplierRegistration", "security": [], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Supplier portal pages" ], "summary": "The paste box for a registration link. A 303 to /supplier-registration/{token}.", "operationId": "postSupplierRegistration", "security": [], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } } } } }, "/supplier-registration/{token}": { "get": { "tags": [ "Supplier portal pages" ], "summary": "The application form: the business, the contact and every document the buyer asks for, in one page.", "operationId": "getSupplierRegistrationByToken", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "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" } } }, "post": { "tags": [ "Supplier portal pages" ], "summary": "Send the application, documents included, as one multipart form. Nothing is stored for an application that is refused; the buyer is told.", "operationId": "postSupplierRegistrationByToken", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier-registration/{token}/sent": { "get": { "tags": [ "Supplier portal pages" ], "summary": "The receipt for a sent application, with its reference.", "operationId": "getSupplierRegistrationByTokenSent", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ref", "in": "query", "required": false, "schema": { "type": "string" }, "example": "REG-0001" }, { "name": "told", "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" } } } }, "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 still waiting. ?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" } ], "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" } } } }, "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", "address": "12 Long Street, Cape Town, 8001", "city": "Cape Town", "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/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": { "type": "object", "properties": { "address": { "type": "string" } } }, "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" } } }, "example": { "everyKm": 15000, "everyMonths": 12, "standingCostPerKm": 2.35 } } } }, "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/PostApiPushTokensResponse" }, "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": { "$ref": "#/components/schemas/PostTrackByTokenUpdatesRequest" }, "example": { "optedOut": true } } } }, "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/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" } } } }, "/track/{token}": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The customer's tracking page for one delivery: status, the driver's first name, an ETA window, and the vehicle on a map only while this stop is next and the tenant holds Driver tracking. ?format=json for the same facts as data. Never another customer's stop.", "operationId": "getTrackByToken", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "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": "json" }, { "name": "notice", "in": "query", "required": false, "schema": { "type": "string" }, "example": "done" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "businessName": { "type": "string" }, "stopType": { "type": "string" }, "status": { "type": "string" }, "headline": { "type": "string" }, "tripDate": { "type": "string", "format": "date" }, "driverFirstName": { "type": "string" }, "promisedWindow": { "type": "string" }, "etaLabel": { "type": "string" }, "etaFrom": { "type": "string", "format": "date" }, "etaTo": { "type": "string", "format": "date" }, "stopsBefore": { "type": "integer" }, "isNext": { "type": "boolean" }, "position": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "recordedAt": { "type": "string" }, "ageMinutes": { "type": "integer" } } }, "mapImageUrl": { "type": "string" }, "mapUnavailableReason": { "type": "string" }, "outcomeLine": { "type": "string" }, "podAvailable": { "type": "boolean" }, "canRate": { "type": "boolean" }, "rating": { "type": "integer" }, "ratingComment": { "type": "string" }, "updatesOptedOut": { "type": "boolean" } } }, "example": { "businessName": "Karoo Fresh Holdings Ltd", "stopType": "delivery", "status": "pending", "headline": "text", "tripDate": "2026-09-01", "driverFirstName": "Karoo Fresh Holdings Ltd", "promisedWindow": "text", "etaLabel": "Karoo Fresh Holdings Ltd", "etaFrom": "2026-09-01", "etaTo": "2026-09-30", "stopsBefore": 1, "isNext": false, "position": { "latitude": 1.0, "longitude": 1.0, "recordedAt": "2026-09-01T09:15:00Z", "ageMinutes": 1 }, "mapImageUrl": "https://app.ledgrsa.com/pay/3f1a7c92", "mapUnavailableReason": "Budget deferred to the next financial year.", "outcomeLine": "text", "podAvailable": false, "canRate": false, "rating": 1, "ratingComment": "Budget deferred to the next financial year.", "updatesOptedOut": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/track/{token}/slot": { "post": { "tags": [ "Logistics & fleet" ], "summary": "The customer books one of the business's delivery slots; it becomes the stop's window. Only while the stop is still to come, only a slot that is offered. A form post answered with a redirect back to the page; JSON is accepted and answered with the tracking facts.", "operationId": "postTrackByTokenSlot", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slot": { "type": "string" } } }, "example": { "slot": "12:00-17:00" } } } }, "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" } } } }, "/track/{token}/rating": { "post": { "tags": [ "Logistics & fleet" ], "summary": "The customer rates the delivery 1–5 with an optional comment, once. A form post answered with a redirect back to the page; JSON is accepted and answered with JSON.", "operationId": "postTrackByTokenRating", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "integer" }, "comment": { "type": "string" } } }, "example": { "rating": 5, "comment": "On time and careful with the pallets" } } } }, "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" } } } }, "/track/{token}/updates": { "post": { "tags": [ "Logistics & fleet" ], "summary": "The customer stops (optedOut true) or restarts delivery updates. A form post answered with a redirect back to the page; JSON is accepted and answered with JSON.", "operationId": "postTrackByTokenUpdates", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostTrackByTokenUpdatesRequest" }, "example": { "optedOut": true } } } }, "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" } } } }, "/portal/pod/{token}": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The proof of delivery for one stop, as a page — the same document the office prints: who signed, when, where, what was handed over, and what it establishes.", "operationId": "getPortalPodByToken", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "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/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", "address": "12 Long Street, Cape Town, 8001", "city": "Cape Town", "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/PostApiPushTokensResponse" }, "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@capeunionmart.co.za", "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/PostApiPushTokensResponse" }, "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@capeunionmart.co.za", "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/PostApiPushTokensResponse" }, "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/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 — 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}/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/PostApiPushTokensResponse" }, "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" } } } }, "/maps/static": { "get": { "tags": [ "Logistics & fleet" ], "summary": "The street-map image itself, proxied so Google's key never reaches a client. Unauthenticated by construction: the HMAC in the query string is the credential and it covers the centre, zoom and size it authorises, so a signed URL cannot be edited into a different request. Registered only when a maps key is configured. Not called directly — GET /api/logistics/tracking/fleet-map mints the signed URL.", "operationId": "getMapsStatic", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "An image.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "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 — 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/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" }, "example": { "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" } } } }, "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": "INV-0001", "payeNumber": "INV-0001", "uifNumber": "INV-0001", "sdlNumber": "INV-0001", "tradingAs": "text", "email": "accounts@capeunionmart.co.za", "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": { "name": { "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" }, "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": { "name": "KMP Cloud (Pty) Ltd", "registrationNumber": "2021/123456/07", "vatNumber": "4123456789", "vatCategory": "Office supplies", "taxNumber": "INV-0001", "payeNumber": "INV-0001", "uifNumber": "INV-0001", "sdlNumber": "INV-0001", "tradingAs": "Karoo Fresh Holdings Ltd", "email": "accounts@capeunionmart.co.za", "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": { "name": { "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" }, "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": { "name": "KMP Cloud (Pty) Ltd", "registrationNumber": "2021/123456/07", "vatNumber": "4123456789", "vatCategory": "Office supplies", "taxNumber": "INV-0001", "payeNumber": "INV-0001", "uifNumber": "INV-0001", "sdlNumber": "INV-0001", "tradingAs": "Karoo Fresh Holdings Ltd", "email": "accounts@capeunionmart.co.za", "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}/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.", "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.", "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" } } }, "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 } } } }, "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.", "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": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedBalanceSheetResponseScope" }, "eliminated": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedTrialBalanceResponseEliminationsExternalItem" } }, "external": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiCompanyHierarchyByIdConsolidatedTrialBalanceResponseEliminationsExternalItem" } }, "eliminatedTurnover": { "type": "number" }, "eliminatedBalances": { "type": "number" }, "externalTurnover": { "type": "number" } } } } }, "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 — 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/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/PostApiIntercompanyTransactionsResponse" } }, "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.", "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", "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/PostApiIntercompanyTransactionsResponse" }, "examples": { "default": { "$ref": "#/components/examples/PostApiIntercompanyTransactionsResponseExample" } } } } }, "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.", "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", "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/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": "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/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/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.", "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/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": true } ] } } }, "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@capeunionmart.co.za", "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.co.za", "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}": { "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 — 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/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@capeunionmart.co.za", "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.co.za", "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@capeunionmart.co.za", "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@capeunionmart.co.za", "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.co.za", "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@capeunionmart.co.za", "accessLevel": "books", "status": "withdrawn", "requestedByName": "Thandi van Wyk", "requestedByEmail": "thandi@vanwyk.co.za", "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.co.za", "addressedTo": "accounts@capeunionmart.co.za", "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": { "type": "object", "properties": { "accessLevel": { "type": "string" } } }, "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@capeunionmart.co.za", "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.", "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" } } }, "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." } } } }, "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/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}/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": { "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": { "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": { "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" } } }, "example": { "exists": false, "optedIn": false, "displayName": "Karoo Fresh Holdings Ltd", "town": "text", "province": "Western Cape", "services": [ "text" ], "contactEmail": "accounts@capeunionmart.co.za", "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" } } } }, "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.co.za", "website": "https://mokoena.co.za" } } } }, "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/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. 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" } } ], "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/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 3 still to come · 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": false, "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": false, "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/migration/preview": { "post": { "tags": [ "Migration & take-on" ], "summary": "Parse and classify without writing. Same code path as apply, so the counts are the counts that will happen.", "operationId": "postApiMigrationPreview", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csvContent": { "type": "string" }, "entity": { "type": "string" } } }, "example": { "csvContent": "name,email\\nAndy Cameron,andy@example.co.za", "entity": "contacts" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "headers": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "detectedColumns": { "$ref": "#/components/schemas/GetApiDocumentsInboxResponseCounts" }, "suggestedEntity": { "type": "string" }, "entityColumns": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GetApiDocumentsInboxResponseCounts" } } } } }, "example": { "headers": [ "text" ], "rows": [ [ "text" ] ], "detectedColumns": { "key": 1 }, "suggestedEntity": "CONTACTS", "entityColumns": { "key": { "key": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/migration/apply-contacts": { "post": { "tags": [ "Migration & take-on" ], "summary": "Write the parsed contacts. Duplicates are matched on email through the same contactMatchKey the CRM conversion uses.", "operationId": "postApiMigrationApplyContacts", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csvContent": { "type": "string" }, "contactTypeOverride": { "type": "string" } } }, "example": { "csvContent": "name,email\\nAndy Cameron,andy@example.co.za", "contactTypeOverride": "supplier" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMigrationApplyBillsResponse" }, "example": { "created": 1, "skipped": 1, "errors": [], "notes": [ "Budget deferred to the next financial year." ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/migration/apply-accounts": { "post": { "tags": [ "Migration & take-on" ], "summary": "Write the parsed chart of accounts. Account-type aliases are normalised through AfsTypes, so a chart imported from another package — which may label the same accounts `revenue` where Ledgr says `income` — does not report nil turnover on the ITR14.", "operationId": "postApiMigrationApplyAccounts", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMigrationApplyBillsRequest" }, "example": { "csvContent": "Account Code,Account Name,Account Type\n1310,Inventory,asset\n6340,Delivery Costs,expense" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "integer" }, "updated": { "type": "integer" }, "skipped": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object" } }, "message": { "type": "string" } } }, "example": { "created": 1, "updated": 1, "skipped": 1, "errors": [], "message": "Saved." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/migration/apply-products": { "post": { "tags": [ "Migration & take-on" ], "summary": "Write the parsed products.", "operationId": "postApiMigrationApplyProducts", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMigrationApplyBillsRequest" }, "example": { "csvContent": "name,email\\nAndy Cameron,andy@example.co.za" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMigrationApplyBillsResponse" }, "example": { "created": 1, "skipped": 1, "errors": [], "notes": [ "Budget deferred to the next financial year." ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/migration/apply-invoices": { "post": { "tags": [ "Migration & take-on" ], "summary": "Write the parsed documents. Existing document numbers are checked against every series so a number on a customer's pre-migration quote is never reissued.", "operationId": "postApiMigrationApplyInvoices", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMigrationApplyBillsRequest" }, "example": { "csvContent": "name,email\\nAndy Cameron,andy@example.co.za" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMigrationApplyBillsResponse" }, "example": { "created": 1, "skipped": 1, "errors": [], "notes": [ "Budget deferred to the next financial year." ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/migration/apply-bills": { "post": { "tags": [ "Migration & take-on" ], "summary": "Write open supplier bills at take-on: one bill per row for what is still owed. They are marked as opening balances — the opening trial balance's trade creditors already holds them — so they post no journal; paying one clears the creditor once.", "operationId": "postApiMigrationApplyBills", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMigrationApplyBillsRequest" }, "example": { "csvContent": "Supplier Invoice Number,Supplier Name,Bill Date,Due Date,Total Including VAT,Amount Due\nS-4471,Karoo Steel (Pty) Ltd,2026-08-01,2026-08-31,2300.00,2300.00" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiMigrationApplyBillsResponse" }, "example": { "created": 3, "skipped": 0, "errors": [], "notes": [ "1 bill(s) were not imported — already paid." ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/migration/apply-trial-balance": { "post": { "tags": [ "Migration & take-on" ], "summary": "Post the opening trial balance as a journal.", "operationId": "postApiMigrationApplyTrialBalance", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csvContent": { "type": "string" }, "asAtDate": { "type": "string", "format": "date" }, "commit": { "type": "boolean" } } }, "example": { "csvContent": "Account Code,Account Name,Debit,Credit\n1100,Bank — Current Account,15000.00,\n3100,Share Capital,,15000.00", "asAtDate": "2026-02-28", "commit": false } } } }, "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/sync/status": { "get": { "tags": [ "Offline sync" ], "summary": "The tenant's sync cursor and clock. Built, and instantiated only in tests.", "operationId": "getApiSyncStatus", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "pendingOperations": { "type": "integer" }, "lastServerSeq": { "type": "integer" }, "serverTimestamp": { "type": "integer" } } }, "example": { "pendingOperations": 1, "lastServerSeq": 1, "serverTimestamp": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sync/pull": { "get": { "tags": [ "Offline sync" ], "summary": "Changes since a cursor. Built and not wired — no client calls it.", "operationId": "getApiSyncPull", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Only rows changed at or after this instant, as an ISO 8601 timestamp.", "schema": { "type": "string" }, "example": "" }, { "name": "nodeId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSyncPullResponseOperationsItem" } }, "serverTimestamp": { "type": "integer" }, "nextSeq": { "type": "integer" } } }, "example": { "operations": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "entityType": "invoice", "entityId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "operation": "text", "payload": "text", "vectorClock": "text", "timestamp": 1 } ], "serverTimestamp": 1, "nextSeq": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/sync/batch": { "post": { "tags": [ "Offline sync" ], "summary": "Push a batch of local changes with their vector clocks. Built and not wired.", "operationId": "postApiSyncBatch", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/GetApiSyncPullResponseOperationsItem" } }, "nodeId": { "type": "string" } } }, "example": { "operations": [ { "id": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "entityType": "", "entityId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03", "operation": "create", "payload": "{\"name\":\"Karoo Fresh Holdings Ltd\",\"contactType\":\"customer\"}", "vectorClock": "{}", "timestamp": 1 } ], "nodeId": "3f1a7c92-5b64-4d0e-9a11-2c7e8b4f6a03" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "array", "items": { "type": "string" } }, "conflicts": { "type": "array", "items": { "type": "object" } } } }, "example": { "accepted": [ "text" ], "conflicts": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ws/inventory": { "get": { "tags": [ "Offline sync" ], "summary": "Real-time stock updates. The socket exists and no client connects to it. Bearer JWT on the handshake, in its own authenticate block so the licence and API-key interceptors do not run on it.", "operationId": "websocketWsInventory", "security": [ { "bearerAuth": [] } ], "responses": { "101": { "description": "Switching protocols to a WebSocket. This operation is the upgrade handshake — an HTTP GET carrying `Upgrade: websocket` — because OpenAPI has no WebSocket method." }, "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/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.co.za", "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" } } } }, "/webhooks/payfast/itn/{tenantId}": { "post": { "tags": [ "Inbound webhooks" ], "summary": "PayFast's instant transaction notification. Signature-verified, confirmed with PayFast, then filed into the payments inbox. The merchant is resolved from the merchant_id PayFast echoes back, so a tenant may hold several.", "operationId": "postWebhooksPayfastItnByTenantId", "security": [], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "matched": { "type": "integer" }, "note": { "type": "string" } } }, "example": { "status": "sent", "matched": 1, "note": "Budget deferred to the next financial year." } } } } } } }, "/webhooks/yoco/invoice/{tenantId}": { "post": { "tags": [ "Inbound webhooks" ], "summary": "Yoco payment events for a TENANT'S OWN invoices. Verified as Standard Webhooks (HMAC-SHA256 over webhook-id.webhook-timestamp.body) against a secret THAT TENANT stored, never a deployment one. A Yoco webhook names no merchant, so the tenant travels in this path — which is routing, not authorisation: the signature must match one of the tenant's own secrets and the invoice reference in the metadata must name the same tenant.", "operationId": "postWebhooksYocoInvoiceByTenantId", "security": [], "parameters": [ { "name": "tenantId", "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" } } } } } } }, "/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 and how many orders it has sent. 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": { "$ref": "#/components/schemas/PostApiChannelsResponse" } }, "example": [ { "id": "5d2b7c1e-9f43-4a8e-b6d0-3c1a2e4f5b67", "kind": "shopify", "label": "Shopify", "storeAddress": "umlazi-tees.myshopify.com", "webhookUrl": "https://app.ledgr.co.za/webhooks/shopify/5d2b7c1e-9f43-4a8e-b6d0-3c1a2e4f5b67", "productsMatched": 12, "ordersTaken": 48, "lastReconciledAt": "2026-10-11T02:00:04Z", "stockLocationId": null, "stockLocationName": null, "payoutsNotTied": 0 } ] } } }, "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.", "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" } } }, "example": { "kind": "shopify", "storeAddress": "umlazi-tees.myshopify.com", "accessToken": "shpat_0123456789abcdef", "webhookSecret": "whsec_0123456789abcdef", "accessSecret": null } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiChannelsResponse" }, "example": { "id": "5d2b7c1e-9f43-4a8e-b6d0-3c1a2e4f5b67", "kind": "shopify", "label": "Shopify", "storeAddress": "umlazi-tees.myshopify.com", "webhookUrl": "https://app.ledgr.co.za/webhooks/shopify/5d2b7c1e-9f43-4a8e-b6d0-3c1a2e4f5b67", "productsMatched": 12, "ordersTaken": 48, "lastReconciledAt": "2026-10-11T02:00:04Z", "stockLocationId": null, "stockLocationName": null, "payoutsNotTied": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/channels/{id}": { "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" } } } }, "/webhooks/whatsapp": { "get": { "tags": [ "Inbound webhooks" ], "summary": "Meta's subscription handshake for the WhatsApp delivery-report webhook: echoes hub.challenge when hub.mode is subscribe and hub.verify_token matches the deployment's WHATSAPP_WEBHOOK_VERIFY_TOKEN; 403 otherwise, and always when none is configured.", "operationId": "getWebhooksWhatsapp", "security": [], "responses": { "200": { "description": "A plain-text download.", "content": { "text/plain": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Inbound webhooks" ], "summary": "Meta's WhatsApp delivery reports (sent, delivered, read, failed). Verified by X-Hub-Signature-256 (HMAC-SHA256 of the raw body with the Meta app secret); unsigned or mis-signed reports are refused 401, and with no WHATSAPP_APP_SECRET configured every report is refused 503. A failed message is taken off the tenant's WhatsApp meter; delivered and read are recorded for the history.", "operationId": "postWebhooksWhatsapp", "security": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "reports": { "type": "integer" }, "applied": { "type": "integer" } } }, "example": { "reports": 1, "applied": 1 } } } } } } }, "/webhooks/{kind}/{connectionId}": { "post": { "tags": [ "Inbound webhooks" ], "summary": "A connected store's order (market-platform T-P3.1, T-P3.2) — {kind} is shopify or woocommerce. Verified with that connection's own webhook secret before anything is read (Shopify: X-Shopify-Hmac-SHA256; WooCommerce: X-WC-Webhook-Signature — each base64 HMAC-SHA256 of the raw body; WooCommerce's unsigned set-up ping is answered and ignored); 401 on a bad signature, 404 for an unknown store, and neither writes. A PAID order becomes one invoice, paid into 1366 Card Payments in Transit; the same order delivered again answers replayed:true and writes nothing.", "operationId": "postWebhooksByKindByConnectionId", "security": [], "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "replayed": { "type": "boolean" }, "ignored": { "type": "boolean" } } }, "example": { "invoiceId": "b1c9e2d4-7a35-4f60-8e12-9d3c4b5a6f78", "replayed": false, "ignored": false } } } } } } }, "/webhooks/yoco/billing": { "post": { "tags": [ "Inbound webhooks" ], "summary": "Yoco events for LEDGR'S OWN licence checkouts — this is what mints and emails a key after a purchase.", "operationId": "postWebhooksYocoBilling", "security": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostApiPushTokensResponse" }, "example": { "status": "IGNORED" } } } } } } }, "/accountant-directory": { "get": { "tags": [ "Platform administration" ], "summary": "The public find-an-accountant directory: every partner practice that chose to be listed and has not been hidden, ordered by province, town and name. Public and unauthenticated. `?q=` narrows by town or province; `?province=` is an exact province id, and an unknown one is refused rather than widened. Carries no account id and nothing the practice did not choose to publish, except whether Ledgr has checked its professional-body registration. Throttled per caller.", "operationId": "getAccountantDirectory", "security": [], "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": "province", "in": "query", "required": false, "schema": { "type": "string" }, "example": "WC" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "listings": { "type": "array", "items": { "type": "object", "properties": { "displayName": { "type": "string" }, "town": { "type": "string" }, "province": { "type": "string" }, "provinceLabel": { "type": "string" }, "services": { "type": "array", "items": { "type": "string" } }, "contactEmail": { "type": "string" }, "website": { "type": "string" }, "registrationVerified": { "type": "boolean" }, "registrationBodyLabel": { "type": "string" } } } }, "total": { "type": "integer" } } }, "example": { "listings": [ { "displayName": "Mokoena & Associates", "town": "Polokwane", "province": "limpopo", "provinceLabel": "Limpopo", "services": [ "Income tax returns", "VAT returns" ], "contactEmail": "hello@mokoena.co.za", "website": "https://mokoena.co.za", "registrationVerified": false, "registrationBodyLabel": "SAICA" } ], "total": 1 } } } } } } }, "/training/certificates/confirm/{token}": { "get": { "tags": [ "Platform administration" ], "summary": "The page a Ledgr Academy certificate's confirmation email links to. Opening it confirms nothing — a mail scanner opens every link — it shows one button that posts back to the same address. An unknown or spent token answers 404.", "operationId": "getTrainingCertificatesConfirmByToken", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Platform administration" ], "summary": "Confirms the address a Ledgr Academy certificate was sent to, and sends the holder to the certificate's public page, where anybody can check it by its number. An unknown or spent token answers 404.", "operationId": "postTrainingCertificatesConfirmByToken", "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" } } } } } } }, "/partner-applications": { "post": { "tags": [ "Platform administration" ], "summary": "A practice asks to join the partner programme. Public and unauthenticated — applying is what precedes having an account. Answers 201 with an acknowledgement and deliberately NO row id and NO status: this response goes to whoever posted it, and an unauthenticated caller has no business enumerating the queue. Re-applying from the same address keeps the later submission beside the live application for the reviewer, never over it, and the answer is the same whether or not an application was already waiting — it names no address and discloses nothing about the queue. Throttled per caller (10 an hour).", "operationId": "postPartnerApplications", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firmName": { "type": "string" }, "contactName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "professionalBody": { "type": "string" }, "membershipNumber": { "type": "string" }, "clientCount": { "type": "integer" }, "website": { "type": "string" }, "note": { "type": "string" } } }, "example": { "firmName": "Mokoena & Associates", "contactName": "Thandi Mokoena", "email": "thandi@mokoena.co.za", "phone": "+27 82 555 0143", "professionalBody": "saica", "membershipNumber": "20123456", "clientCount": 40, "website": "https://mokoena.co.za", "note": "Mostly small retailers and two trusts." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostStatusSubscribeResponse" }, "example": { "received": true, "message": "Thank you — your application is with us." } } } } } } }, "/callback-requests": { "post": { "tags": [ "Platform administration" ], "summary": "Ask Ledgr to telephone you (the support page's \"Request a callback\"). Public and unauthenticated — the caller may have no account. Name, email, a number with 9 to 15 digits, a `window` (`morning`, `afternoon` or `any`, all inside business days 08:00–17:00 SAST) and a `topic` are required; every missing field is reported at once. Answers 201 with an acknowledgement and deliberately no row id, and emails one confirmation to the address given — outside the transaction, so a deployment with no mail credentials still takes the request. Throttled per caller (5 an hour).", "operationId": "postCallbackRequests", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "window": { "type": "string" }, "topic": { "type": "string" }, "message": { "type": "string" } } }, "example": { "name": "Thandi Mokoena", "email": "thandi@mokoena.co.za", "phone": "082 555 0143", "window": "morning", "topic": "payroll-sars", "message": "Our EMP201 will not balance to the payroll run." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostStatusSubscribeResponse" }, "example": { "received": true, "message": "Thank you — a member of our support team will call you back, morning, 08:00–12:00 SAST (business days, 08:00–17:00 SAST). We have sent a confirmation to your email address." } } } } } } }, "/status/incidents": { "get": { "tags": [ "Platform administration" ], "summary": "The public status page's incidents: `current` is every open incident (the banner on /health), `history` every resolved one that started in the last `historyDays` (90) days, each with its updates newest first. The same snapshot /health draws, so the page and this answer cannot disagree. Public; no account needed.", "operationId": "getStatusIncidents", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "current": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "component": { "type": "string" }, "componentLabel": { "type": "string" }, "severity": { "type": "string" }, "severityLabel": { "type": "string" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "startedAt": { "type": "string" }, "resolvedAt": { "type": "null" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "message": { "type": "string" }, "postedAt": { "type": "string" }, "emailedCount": { "type": "null" }, "emailFailedCount": { "type": "null" }, "emailSkippedReason": { "type": "null" } } } } } } }, "history": { "type": "array", "items": { "type": "object" } }, "historyDays": { "type": "integer" } } }, "example": { "current": [ { "id": "5b1f0c7e-2a44-4e0b-9f3c-8d2a61e7c4b9", "title": "Card payments are failing for some customers", "component": "payments", "componentLabel": "Card payments and payment links", "severity": "partial-outage", "severityLabel": "Partial outage", "status": "identified", "statusLabel": "Cause identified", "startedAt": "2026-09-26T07:40:00Z", "resolvedAt": null, "updates": [ { "id": "c3d9a8f1-0b7e-4d62-a1f5-6e2c9b4d8a70", "status": "identified", "statusLabel": "Cause identified", "message": "The card gateway is timing out. Payment links still open; paying may need a second try.", "postedAt": "2026-09-26T08:05:00Z", "emailedCount": null, "emailFailedCount": null, "emailSkippedReason": null } ] } ], "history": [], "historyDays": 90 } } } } } } }, "/status/subscribe": { "post": { "tags": [ "Platform administration" ], "summary": "Ask to be emailed each status update — double opt-in. The address is stored as pending and sent a confirmation link; NOTHING else reaches it until that link is followed and confirmed. Answers 202 with one sentence whatever is already on file, so it cannot be used to ask whether an address uses Ledgr; an address is invited at most once a day. 503 when the server has no public address to put in the link. Also accepts a plain form post (the /health page's form), which answers a page. Throttled per caller (10 an hour).", "operationId": "postStatusSubscribe", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostStatusSubscribeRequest" }, "example": { "email": "ops@mokoena.co.za" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostStatusSubscribeResponse" }, "example": { "received": true, "message": "Thank you. If that address can receive email, a confirmation link is on its way — nothing is sent to it until the link is followed." } } } } } } }, "/status/confirm": { "get": { "tags": [ "Platform administration" ], "summary": "The page a confirmation email's link opens (`?s=&sig=`). It confirms nothing by itself — a mail scanner that prefetches the link must not be able to opt somebody in — and shows a button that posts to the route below.", "operationId": "getStatusConfirm", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sig", "in": "query", "required": false, "schema": { "type": "string" }, "example": "%3Csignature%3E" }, { "name": "s", "in": "query", "required": false, "schema": { "type": "string" }, "example": "s" } ], "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" } } }, "post": { "tags": [ "Platform administration" ], "summary": "Confirm a status subscription: the confirmation page's form posts `s` and `sig` (form-encoded). A signature made for unsubscribing is refused here. Answers a page.", "operationId": "postStatusConfirm", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "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" } } } }, "/status/unsubscribe": { "get": { "tags": [ "Platform administration" ], "summary": "One-click unsubscribe from status emails (`?s=&sig=`), linked from every one of them. No sign-in, no expiry, idempotent; nothing else Ledgr sends is affected. Answers a page.", "operationId": "getStatusUnsubscribe", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "s", "in": "query", "required": false, "schema": { "type": "string" }, "example": "s" }, { "name": "sig", "in": "query", "required": false, "schema": { "type": "string" }, "example": "%3Csignature%3E" } ], "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" } } } }, "/community/": { "get": { "tags": [ "Platform administration" ], "summary": "The community Q&A's list page: published questions, newest first, 20 a page (`?page=`, a whole number from 1 — anything else is refused). Server-rendered and crawlable. Only posts a moderator has approved appear; authors are shown by first name and last initial, never an email.", "operationId": "getCommunitySlash", "security": [], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } } }, "/community": { "get": { "tags": [ "Platform administration" ], "summary": "Redirects to /community/.", "operationId": "getCommunity", "security": [], "responses": { "302": { "description": "A redirect — follow the Location header.", "headers": { "Location": { "description": "Where the browser is sent next.", "schema": { "type": "string" } } } } } } }, "/community/questions/{id}": { "get": { "tags": [ "Platform administration" ], "summary": "One published question with its published answers, server-rendered. A question waiting for moderation, rejected or hidden answers 404 — indistinguishable from one that never existed.", "operationId": "getCommunityQuestionsById", "security": [], "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" } } } } } } }, "/community/questions": { "post": { "tags": [ "Platform administration" ], "summary": "Ask the community a question. Needs a signed-in Ledgr account (any plan, any role). The post is stored as `pending` and is NOT public until a moderator approves it. Bounded per account from its own recent posts (5 an hour, 20 a day) — over that answers 409 with the sentence to show.", "operationId": "postCommunityQuestions", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" } } }, "example": { "title": "How do I record a deposit paid before the invoice?", "body": "The customer paid 50% up front. Where does that go until I invoice?" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCommunityQuestionsResponse" }, "example": { "id": "9e4b2c10-7d3a-4f85-b6e1-2a9c0f5d8e37", "state": "pending", "message": "Thank you — your post is waiting for a moderator. It appears on the site once it has been read, usually within a working day." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/community/questions/{id}/answers": { "post": { "tags": [ "Platform administration" ], "summary": "Answer a published question. Same rules as asking: a signed-in account, `pending` until a moderator approves it, and the same per-account bound. A question that is not public answers 404.", "operationId": "postCommunityQuestionsByIdAnswers", "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" } } }, "example": { "body": "Raise a deposit invoice first; it posts to Deferred Revenue until you apply it to the final invoice." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCommunityQuestionsResponse" }, "example": { "id": "4c7f1e92-0a5b-4d3e-8f26-b1d9e0a7c563", "state": "pending", "message": "Thank you — your post is waiting for a moderator. It appears on the site once it has been read, usually within a working day." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/community/posts/{id}/report": { "post": { "tags": [ "Platform administration" ], "summary": "Report a published post. It comes off the site at once and goes back to the moderation queue with the `reason`, which is required. One report per person per post; 10 reports an hour per account.", "operationId": "postCommunityPostsByIdReport", "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": "Advertises a competing product." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCommunityQuestionsResponse" }, "example": { "id": "4c7f1e92-0a5b-4d3e-8f26-b1d9e0a7c563", "state": "pending", "message": "Thank you. The post is off the site until a moderator has looked at it again." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/announcements/unsubscribe": { "get": { "tags": [ "Platform administration" ], "summary": "The customer-facing half of an announcement: the one-click opt-out its footer links to. Public and unauthenticated by design — the reader is in an email client with no session, and POPIA s69(3) asks for a reasonable opportunity to object, which a password prompt is not. Authorisation is an HMAC over the tenant id in the query string. Deliberately has NO expiry, unlike every other signed link here: an expired unsubscribe link is the exact failure the mechanism exists to prevent. Idempotent, so a mail client's prefetch followed by the reader's own click is one opt-out and one page. It stops product announcements only — invoices, reminders, statements and anything about the subscription are unaffected.", "operationId": "getAnnouncementsUnsubscribe", "security": [], "parameters": [ { "name": "t", "in": "query", "required": false, "schema": { "type": "string" }, "example": "%3Ctoken%3E" }, { "name": "a", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "1" }, { "name": "sig", "in": "query", "required": false, "schema": { "type": "string" }, "example": "%3Csignature%3E" } ], "responses": { "200": { "description": "An HTML page, for a browser rather than an API client.", "content": { "text/html": { "schema": { "type": "object" } } } } } } }, "/health": { "get": { "tags": [ "Operations & discovery" ], "summary": "Liveness. Deliberately ignores the database — a liveness probe that fails during a Cloud SQL blip would kill every instance of a revision that was fine.", "operationId": "getHealth", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" } } }, "example": { "status": "ok", "service": "ledgr-api" } } } } } } }, "/readyz": { "get": { "tags": [ "Operations & discovery" ], "summary": "Readiness, and the service's startup probe: 200 only when the startup database init reported ok AND a live SELECT 1 succeeds. This is what stops a container that boots with a broken migration from being promoted to 100% of traffic.", "operationId": "getReadyz", "security": [], "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/openapi.json": { "get": { "tags": [ "Operations & discovery" ], "summary": "The OpenAPI 3.1 document, at the conventional root path tools probe for. Generated from this same catalogue, so the two can never disagree. The customer API only: the back office (/admin, /internal, /diagnostics) is in GET /admin/openapi.json.", "operationId": "getOpenapi.json", "security": [], "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api-docs/openapi.json": { "get": { "tags": [ "Operations & discovery" ], "summary": "The same document, on a path an integrator can be given without it looking like an internal admin URL.", "operationId": "getApiDocsOpenapi.json", "security": [], "responses": { "200": { "description": "Success — a JSON body. No example is published for this endpoint.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/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" } } } } } } }, "/docs/search.json": { "get": { "tags": [ "Operations & discovery" ], "summary": "The documentation search index, shipped as data for the browser to filter rather than as a search endpoint — the whole corpus is about 60 KB, so a request per keystroke would cost more than sending it once, and it keeps working on a flaky connection.", "operationId": "getDocsSearch.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:).", "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" } } } } }, "example": { "clientId": "6f1d2c7a-3b4e-3c5d-9e8f-0a1b2c3d4e5f", "kind": "sales", "journalDate": "2026-10-01", "reference": "aura: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 } } } } }, "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:.", "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" } } } } } }