{ "openapi": "3.1.0", "info": { "title": "Mikono API", "version": "1.13.0", "description": "Integration API for Mikono ERP. JSON only, camelCase fields, ISO 8601 UTC times, money as `{ amount: \"\", currency }`. Errors are RFC 9457 `application/problem+json` with a stable `code`. Every response carries `X-Request-Id`. Unknown request fields are rejected; clients must ignore unknown response fields." }, "servers": [ { "url": "https://calculating-gnu-991.convex.site/api/v1", "description": "Sandbox (mk_test_ keys)" }, { "url": "https://keen-lark-812.eu-west-1.convex.site/api/v1", "description": "Production (mk_live_ keys)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Credit notes" }, { "name": "Customers" }, { "name": "DMS", "description": "Documents from a distributor management system in Mikono's canonical JSON or XML (EDGE 365 mapping is planned) and the update flags Mikono returns for them." }, { "name": "Field activity" }, { "name": "Invoices" }, { "name": "Locations" }, { "name": "Orders" }, { "name": "Payments" }, { "name": "Products" }, { "name": "Returns" }, { "name": "Routes" }, { "name": "Stock" }, { "name": "System", "description": "Health, key introspection and this document." }, { "name": "Trips" } ], "paths": { "/competitor-observations": { "get": { "operationId": "listCompetitorObservations", "summary": "List competitor stock observations", "description": "Bag counts per brand seen at depots and outlets, newest observation date first. `photoUrl` appears only with `customers:pii`. Photo URLs are short-lived signed URLs: download the photo promptly and do not store the URL.", "tags": [ "Field activity" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "customerId", "in": "query", "required": false, "description": "Only this site's observations.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitorObservationPage" }, "example": { "data": [ { "id": "ky73x5z7b9d1f3h5k7m9p1r3t5v7x9z1", "siteKind": "retailer", "customerId": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "brand": "Nile Special", "isOwnBrand": false, "quantity": 12, "observedAt": "2026-10-02", "observedBy": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "visitId": "kw79t1v3x5z7b9d1f3h5k7m9p1r3t5v7", "photoUrl": null, "createdAt": "2026-10-02T07:11:00.000Z", "updatedAt": "2026-10-02T07:11:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "trips:read" ], "x-mikono-idempotency": "none" } }, "/credit-notes": { "get": { "operationId": "listCreditNotes", "summary": "List credit notes", "description": "Newest first, or oldest change first with `updatedSince` (a resumable change feed: a write can become visible a few seconds after its `updatedAt`, so poll from your last checkpoint minus 5 minutes and skip records whose id and `updatedAt` you already processed). Filters run on each page, so a page can hold fewer than `limit` records while `hasMore` is true. The embedded customer's phone and TIN need `customers:pii`.", "tags": [ "Returns" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "status", "in": "query", "required": false, "description": "Only credit notes with this status.", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "required": false, "description": "Only documents of the customer with this Mikono id.", "schema": { "type": "string" } }, { "name": "invoiceId", "in": "query", "required": false, "description": "Only credit notes raised against this invoice.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNotePage" }, "example": { "data": [ { "id": "kz75b7d9f1h3k5m7p9r1t3v5x7z9b1d3", "creditNoteNumber": "CN-000027", "status": "applied", "type": "return", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "invoiceId": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "returnId": "kq73z5b7d9f1h3k5m7p9r1t3v5x7z9b1", "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "issueDate": "2026-10-02", "reason": "Damaged on delivery", "notes": null, "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "code": "780256", "name": "Tusker Lager 500ml" }, "description": "Tusker Lager 500ml", "type": "product", "quantity": 2, "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "915.25", "currency": "UGX" }, "amount": { "amount": "6000.00", "currency": "UGX" } } ], "linesTruncated": false, "subtotal": { "amount": "6000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "tax": { "amount": "915.25", "currency": "UGX" }, "total": { "amount": "6000.00", "currency": "UGX" }, "remainingAmount": { "amount": "0.00", "currency": "UGX" }, "cashRefundAmount": null, "currency": "UGX", "applications": [ { "invoiceId": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "invoiceNumber": "INV-000412", "amount": { "amount": "6000.00", "currency": "UGX" }, "date": "2026-10-02", "refundPaymentId": null } ], "fiscal": { "status": null, "fdn": null, "verificationCode": null, "qrCode": null, "fiscalisedAt": null }, "posting": { "status": "posted", "quickbooksRef": "212", "quickbooksType": "CreditMemo", "reason": null }, "externalCodes": { "quickbooks": "212" }, "createdAt": "2026-10-02T07:12:30.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "returns:read" ], "x-mikono-idempotency": "none" }, "post": { "operationId": "createCreditNote", "summary": "Create a credit note", "description": "Issues and posts a credit note (DR revenue and VAT, CR receivables) and applies it to `invoiceId`'s open balance first; the rest stays on the customer's account. A credit against an invoice sold on a delivery trip carries that trip (`tripId`) and counts in its settlement. Goods coming back are a return (`POST /returns`), which restocks them. The document is posted at once, as Go's van sale is: API writes go through Mikono's server-side cores, which apply no amount-tiered approval. A reference inside the body that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field.", "tags": [ "Credit notes" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteCreate" }, "example": { "customer": { "code": "UG2104417" }, "invoiceId": "jn7c2v6b1n9m3q8w4e7r2t5y0u6i1o3p", "type": "adjustment", "reason": "Price correction", "lines": [ { "product": { "code": "780116" }, "quantity": 50, "unitPrice": { "amount": "100.00", "currency": "UGX" } } ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" }, "example": { "id": "jc71m4n7b0v3c6x9z2l5k8j1h4g7f0d3", "creditNoteNumber": "CN-000045", "status": "applied", "type": "adjustment", "customer": { "id": "k171w2qv0x3r8m7s5d2c9b4n6h7m3p1a", "name": "Kisementi Bar", "code": "UG2104417" }, "invoiceId": "jn7c2v6b1n9m3q8w4e7r2t5y0u6i1o3p", "returnId": null, "tripId": null, "issueDate": "2026-10-02", "reason": "Price correction", "notes": null, "lines": [ { "product": { "id": "k572a9b8c7d6e5f4g3h2j1k0m9n8p7q6", "code": "780116", "name": "Bell Lager 500ml" }, "description": "Bell Lager 500ml", "type": "adjustment", "quantity": 50, "unitPrice": { "amount": "100.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "900.00", "currency": "UGX" }, "amount": { "amount": "5000.00", "currency": "UGX" } } ], "linesTruncated": false, "subtotal": { "amount": "5000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "tax": { "amount": "900.00", "currency": "UGX" }, "total": { "amount": "5900.00", "currency": "UGX" }, "remainingAmount": { "amount": "0.00", "currency": "UGX" }, "cashRefundAmount": null, "currency": "UGX", "applications": [ { "invoiceId": "jn7c2v6b1n9m3q8w4e7r2t5y0u6i1o3p", "invoiceNumber": "INV-000123", "amount": { "amount": "5900.00", "currency": "UGX" }, "date": "2026-10-02", "refundPaymentId": null } ], "fiscal": { "status": null, "fdn": null, "verificationCode": null, "qrCode": null, "fiscalisedAt": null }, "posting": { "status": "pending", "quickbooksRef": null, "quickbooksType": null, "reason": null }, "externalCodes": {}, "createdAt": "2026-10-02T10:00:00.000Z", "updatedAt": "2026-10-02T10:00:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `idempotency_key_required`, `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`, `invalid_state`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `currency_not_supported`, `customer_not_found`, `idempotency_key_reused`, `invoice_not_found`, `period_closed`, `product_not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "returns:write" ], "x-mikono-idempotency": "required" } }, "/credit-notes/by-code/{system}/{code}": { "get": { "operationId": "getCreditNoteByCode", "summary": "Get a credit note by external code", "tags": [ "Returns" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "Code system: `dms` or a registered partner system (`edge365`).", "examples": [ "dms" ] } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The record's code in that system: trimmed, case-sensitive, at most 64 characters.", "examples": [ "UG2000123" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" }, "example": { "id": "kz75b7d9f1h3k5m7p9r1t3v5x7z9b1d3", "creditNoteNumber": "CN-000027", "status": "applied", "type": "return", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "invoiceId": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "returnId": "kq73z5b7d9f1h3k5m7p9r1t3v5x7z9b1", "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "issueDate": "2026-10-02", "reason": "Damaged on delivery", "notes": null, "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "code": "780256", "name": "Tusker Lager 500ml" }, "description": "Tusker Lager 500ml", "type": "product", "quantity": 2, "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "915.25", "currency": "UGX" }, "amount": { "amount": "6000.00", "currency": "UGX" } } ], "linesTruncated": false, "subtotal": { "amount": "6000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "tax": { "amount": "915.25", "currency": "UGX" }, "total": { "amount": "6000.00", "currency": "UGX" }, "remainingAmount": { "amount": "0.00", "currency": "UGX" }, "cashRefundAmount": null, "currency": "UGX", "applications": [ { "invoiceId": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "invoiceNumber": "INV-000412", "amount": { "amount": "6000.00", "currency": "UGX" }, "date": "2026-10-02", "refundPaymentId": null } ], "fiscal": { "status": null, "fdn": null, "verificationCode": null, "qrCode": null, "fiscalisedAt": null }, "posting": { "status": "posted", "quickbooksRef": "212", "quickbooksType": "CreditMemo", "reason": null }, "externalCodes": { "quickbooks": "212" }, "createdAt": "2026-10-02T07:12:30.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "returns:read" ], "x-mikono-idempotency": "none" } }, "/credit-notes/{id}": { "get": { "operationId": "getCreditNote", "summary": "Get a credit note", "description": "With lines, applications to invoices, EFRIS fiscal status and QuickBooks posting status.", "tags": [ "Returns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" }, "example": { "id": "kz75b7d9f1h3k5m7p9r1t3v5x7z9b1d3", "creditNoteNumber": "CN-000027", "status": "applied", "type": "return", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "invoiceId": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "returnId": "kq73z5b7d9f1h3k5m7p9r1t3v5x7z9b1", "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "issueDate": "2026-10-02", "reason": "Damaged on delivery", "notes": null, "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "code": "780256", "name": "Tusker Lager 500ml" }, "description": "Tusker Lager 500ml", "type": "product", "quantity": 2, "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "915.25", "currency": "UGX" }, "amount": { "amount": "6000.00", "currency": "UGX" } } ], "linesTruncated": false, "subtotal": { "amount": "6000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "tax": { "amount": "915.25", "currency": "UGX" }, "total": { "amount": "6000.00", "currency": "UGX" }, "remainingAmount": { "amount": "0.00", "currency": "UGX" }, "cashRefundAmount": null, "currency": "UGX", "applications": [ { "invoiceId": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "invoiceNumber": "INV-000412", "amount": { "amount": "6000.00", "currency": "UGX" }, "date": "2026-10-02", "refundPaymentId": null } ], "fiscal": { "status": null, "fdn": null, "verificationCode": null, "qrCode": null, "fiscalisedAt": null }, "posting": { "status": "posted", "quickbooksRef": "212", "quickbooksType": "CreditMemo", "reason": null }, "externalCodes": { "quickbooks": "212" }, "createdAt": "2026-10-02T07:12:30.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "returns:read" ], "x-mikono-idempotency": "none" } }, "/credit-notes/{id}/cancel": { "post": { "operationId": "cancelCreditNote", "summary": "Cancel a credit note", "description": "Voids an issued credit note and everything it posted: credit taken back off invoices, restocked goods out again, journals reversed. `409 invalid_state` when the note is already cancelled, was refunded in cash, was raised by a return (`POST /returns`: it restocked goods and the van's trip counts them; reverse the return in Mikono instead), or is (or is about to be) in QuickBooks, which Mikono cannot void there yet. A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`.", "tags": [ "Credit notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this operation; same semantics as on creates.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteCancel" }, "example": { "reason": "Raised twice" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" }, "example": { "id": "jc71m4n7b0v3c6x9z2l5k8j1h4g7f0d3", "creditNoteNumber": "CN-000045", "status": "voided", "type": "adjustment", "customer": { "id": "k171w2qv0x3r8m7s5d2c9b4n6h7m3p1a", "name": "Kisementi Bar", "code": "UG2104417" }, "invoiceId": "jn7c2v6b1n9m3q8w4e7r2t5y0u6i1o3p", "returnId": null, "tripId": null, "issueDate": "2026-10-02", "reason": "Price correction", "notes": null, "lines": [ { "product": { "id": "k572a9b8c7d6e5f4g3h2j1k0m9n8p7q6", "code": "780116", "name": "Bell Lager 500ml" }, "description": "Bell Lager 500ml", "type": "adjustment", "quantity": 50, "unitPrice": { "amount": "100.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "900.00", "currency": "UGX" }, "amount": { "amount": "5000.00", "currency": "UGX" } } ], "linesTruncated": false, "subtotal": { "amount": "5000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "tax": { "amount": "900.00", "currency": "UGX" }, "total": { "amount": "5900.00", "currency": "UGX" }, "remainingAmount": { "amount": "0.00", "currency": "UGX" }, "cashRefundAmount": null, "currency": "UGX", "applications": [], "fiscal": { "status": null, "fdn": null, "verificationCode": null, "qrCode": null, "fiscalisedAt": null }, "posting": { "status": "pending", "quickbooksRef": null, "quickbooksType": null, "reason": null }, "externalCodes": {}, "createdAt": "2026-10-02T10:00:00.000Z", "updatedAt": "2026-10-02T10:00:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`, `invalid_state`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `idempotency_key_reused`, `insufficient_stock`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "returns:write" ], "x-mikono-idempotency": "optional" } }, "/customers": { "get": { "operationId": "listCustomers", "summary": "List customers (outlets)", "description": "Newest first, or oldest change first with `updatedSince` (a resumable change feed). Filters run on each page, so a page can hold fewer than `limit` records while `hasMore` is true. `balance` is null in lists. Contacts, GPS and TIN need `customers:pii`.", "tags": [ "Customers" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "status", "in": "query", "required": false, "description": "Only outlets with this status.", "schema": { "type": "string", "enum": [ "active", "inactive", "pending", "archived" ] } }, { "name": "routeCode", "in": "query", "required": false, "description": "Only active stops of the route with this code.", "schema": { "type": "string" } }, { "name": "territory", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "includeDeleted", "in": "query", "required": false, "description": "Also return deleted records, as tombstones `{ id, deleted: true, deletedAt }`.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPage" }, "example": { "data": [ { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "shortName": "Hilltop", "status": "active", "type": "cash", "channel": "On-trade", "subChannel": "Bar", "segment": null, "subSegments": [], "volumeGrade": "medium", "territory": "Ntinda", "routes": [ { "id": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "code": "KBDVSM001" } ], "priceGroup": "retail", "creditLimit": null, "creditTerms": null, "creditStatus": null, "balance": { "amount": "0.00", "currency": "UGX" }, "externalCodes": { "dms": "UG2104417" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z", "location": { "address": { "street": "Ntinda Road", "city": "Kampala", "region": "Central", "postalCode": null, "country": "UG" } } } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "customers:read" ], "x-mikono-idempotency": "none" }, "post": { "operationId": "createCustomer", "summary": "Create a customer (outlet)", "description": "Creates an outlet through Mikono's customer core. `taxId`, `location.gps` and `contact` need `customers:pii` as well. With `externalCodes.dms` set to a code another outlet carries, answers `409 code_conflict`; use `PUT /customers/by-code/dms/{code}` to create-or-update by code. API writes run the same core as the Mikono app, attributed to the key's service actor, with an audit row (source Integration). Amount-tiered approval does not apply: the document is posted, not left for approval.", "tags": [ "Customers" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreate" }, "example": { "name": "Mama Joy Shop, Ntinda", "type": "cash", "channel": "Bar", "territory": "Ntinda", "location": { "address": { "street": "Ntinda Road", "city": "Kampala", "country": "Uganda" } }, "externalCodes": { "dms": "UG2104417" } } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "kd7cust0000000000000000000000001", "name": "Mama Joy Shop, Ntinda", "shortName": null, "status": "active", "type": "cash", "channel": "Bar", "subChannel": null, "segment": null, "subSegments": [], "volumeGrade": null, "territory": "Ntinda", "routes": [], "priceGroup": null, "creditLimit": null, "creditTerms": null, "creditStatus": null, "balance": { "amount": "0.00", "currency": "UGX" }, "location": { "address": { "street": "Ntinda Road", "city": "Kampala", "region": null, "postalCode": null, "country": "Uganda" } }, "externalCodes": { "dms": "UG2104417" }, "createdAt": "2026-10-02T07:15:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `idempotency_key_required`, `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `code_conflict`, `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "customers:write" ], "x-mikono-idempotency": "required" } }, "/customers/by-code/{system}/{code}": { "get": { "operationId": "getCustomerByCode", "summary": "Get a customer by external code", "description": "`GET /customers/by-code/dms/UG2000123` finds the outlet with that DMS code. A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`.", "tags": [ "Customers" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "Code system: `dms` or a registered partner system (`edge365`).", "examples": [ "dms" ] } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The record's code in that system: trimmed, case-sensitive, at most 64 characters.", "examples": [ "UG2000123" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "shortName": "Hilltop", "status": "active", "type": "cash", "channel": "On-trade", "subChannel": "Bar", "segment": null, "subSegments": [], "volumeGrade": "medium", "territory": "Ntinda", "routes": [ { "id": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "code": "KBDVSM001" } ], "priceGroup": "retail", "creditLimit": null, "creditTerms": null, "creditStatus": null, "balance": { "amount": "0.00", "currency": "UGX" }, "location": { "address": { "street": "Ntinda Road", "city": "Kampala", "region": "Central", "postalCode": null, "country": "UG" }, "gps": { "latitude": 0.350849, "longitude": 32.612542 } }, "taxId": null, "contacts": [ { "name": "Outlet manager", "phone": "+256700001001", "email": null, "title": "Manager", "isPrimary": true } ], "externalCodes": { "dms": "UG2104417" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "customers:read" ], "x-mikono-idempotency": "none" }, "put": { "operationId": "upsertCustomerByCode", "summary": "Create or update a customer by external code", "description": "Creates the outlet when no outlet has this code (201), else updates the fields sent (200). Sending the same body twice changes nothing the second time. Only `dms` codes are writable. `taxId`, `location.gps` and `contact` need `customers:pii` (403 `insufficient_scope` otherwise). `Idempotency-Key` is optional: the code makes a retry safe. A reference inside the request body (an outlet, product or route code or id) that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field.", "tags": [ "Customers" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "Code system: `dms` or a registered partner system (`edge365`).", "examples": [ "dms" ] } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The record's code in that system: trimmed, case-sensitive, at most 64 characters.", "examples": [ "UG2000123" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this operation; same semantics as on creates.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpsert" }, "example": { "name": "Mama Joy Shop", "type": "cash", "status": "active", "territory": "Ntinda", "contact": { "phone": "+256772123456" } } } } }, "responses": { "200": { "description": "Updated; 201 when created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "shortName": "Hilltop", "status": "active", "type": "cash", "channel": "On-trade", "subChannel": "Bar", "segment": null, "subSegments": [], "volumeGrade": "medium", "territory": "Ntinda", "routes": [ { "id": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "code": "KBDVSM001" } ], "priceGroup": "retail", "creditLimit": null, "creditTerms": null, "creditStatus": null, "balance": { "amount": "0.00", "currency": "UGX" }, "location": { "address": { "street": "Ntinda Road", "city": "Kampala", "region": "Central", "postalCode": null, "country": "UG" }, "gps": { "latitude": 0.350849, "longitude": 32.612542 } }, "taxId": null, "contacts": [ { "name": "Outlet manager", "phone": "+256700001001", "email": null, "title": "Manager", "isPrimary": true } ], "externalCodes": { "dms": "UG2104417" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `code_conflict`, `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "customers:write" ], "x-mikono-idempotency": "optional" } }, "/customers/{id}": { "get": { "operationId": "getCustomer", "summary": "Get a customer", "description": "A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`.", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "shortName": "Hilltop", "status": "active", "type": "cash", "channel": "On-trade", "subChannel": "Bar", "segment": null, "subSegments": [], "volumeGrade": "medium", "territory": "Ntinda", "routes": [ { "id": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "code": "KBDVSM001" } ], "priceGroup": "retail", "creditLimit": null, "creditTerms": null, "creditStatus": null, "balance": { "amount": "0.00", "currency": "UGX" }, "location": { "address": { "street": "Ntinda Road", "city": "Kampala", "region": "Central", "postalCode": null, "country": "UG" }, "gps": { "latitude": 0.350849, "longitude": 32.612542 } }, "taxId": null, "contacts": [ { "name": "Outlet manager", "phone": "+256700001001", "email": null, "title": "Manager", "isPrimary": true } ], "externalCodes": { "dms": "UG2104417" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "customers:read" ], "x-mikono-idempotency": "none" }, "patch": { "operationId": "patchCustomer", "summary": "Update a customer", "description": "Sets the fields sent; omitted fields keep their value. A field this endpoint does not accept is `400 unknown_field`. `taxId`, `location.gps` and `contact` need `customers:pii`. `Idempotency-Key` is optional. A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`. API writes run the same core as the Mikono app, attributed to the key's service actor, with an audit row (source Integration). Amount-tiered approval does not apply: the document is posted, not left for approval.", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this operation; same semantics as on creates.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpsert" }, "example": { "territory": "Kisaasi", "creditTerms": "Net 7" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "kd7cust0000000000000000000000001", "name": "Mama Joy Shop, Ntinda", "shortName": null, "status": "active", "type": "cash", "channel": "Bar", "subChannel": null, "segment": null, "subSegments": [], "volumeGrade": null, "territory": "Kisaasi", "routes": [], "priceGroup": null, "creditLimit": null, "creditTerms": "Net 7", "creditStatus": null, "balance": { "amount": "0.00", "currency": "UGX" }, "location": { "address": { "street": "Ntinda Road", "city": "Kampala", "region": null, "postalCode": null, "country": "Uganda" } }, "externalCodes": { "dms": "UG2104417" }, "createdAt": "2026-10-02T07:15:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `code_conflict`, `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "customers:write" ], "x-mikono-idempotency": "optional" } }, "/dms/{system}/documents": { "post": { "operationId": "postDmsDocuments", "summary": "Send DMS documents", "description": "Send one DMS document, or up to 500 as `{ documents: [...] }`, in Mikono's canonical form. Mikono stores them and answers with one flag per document, in request order: `received` when it passed the format checks, `rejected` with a reason code when it did not (another distributor code is `R07`; the same document number with different content and the same status is `R05`). Posting into Mikono and QuickBooks happens afterwards; follow it with `GET /dms/{system}/flags`, the `dms.document.flagged` webhook, or your callback URL.\n\nResending a document that was already received returns its current flag and posts nothing. A changed `dmsStatus` (Confirmed to Cancelled) is an update: the old version becomes `superseded`. Send an `Idempotency-Key` with every call; a retry with the same key and body replays the first answer.\n\nSync mode (`?mode=sync`, or set as the connection's default) posts before answering, at most 50 documents a call, and spends at most 25 seconds doing so; documents that are not final by then come back `received` with a `note`, such as `Waiting for QuickBooks`.\n\nThe API is strict: a field Mikono does not know, anywhere in a document, is `400 unknown_field`. `system` must name an enabled DMS connection of your organisation (`canonical` today), else `404 not_found`.", "tags": [ "DMS" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "The partner system the documents come from: `canonical` (Mikono's own JSON) today; `edge365` once EABL's format is mapped (planned). It must match an enabled DMS connection of your organisation.", "examples": [ "canonical" ] } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "mode", "in": "query", "required": false, "description": "`async` (default unless the connection says otherwise): answer with Received or Rejected now and post afterwards. `sync`: post before answering, at most 50 documents a call.", "schema": { "type": "string", "enum": [ "async", "sync" ] } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmsDocuments" }, "example": { "documents": [ { "documentType": "sale_invoice", "documentNumber": "CSKBDVSM001000123", "distributorCode": "KBD001", "documentDate": "2026-10-02", "dmsStatus": "Confirmed", "salesmanCode": "KBDVSM001", "customerCode": "UG0000101", "currency": "UGX", "total": 30000, "body": { "paymentTerms": "cash", "lines": [ { "productCode": "100231", "quantity": 10, "unit": "CS", "unitPrice": 3000, "lineType": "selling" } ] } } ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmsIngestResult" }, "example": { "batchId": "jd7f1h2k3m4n5p6q7r8s9t0v1w2x3y4z", "batchStatus": "parsed", "mode": "async", "duplicate": false, "flags": [ { "documentId": "k57a2b3c4d5e6f7g8h9j0k1m2n3p4q5r", "distributorCode": "KBD001", "documentType": "sale_invoice", "documentNumber": "CSKBDVSM001000123", "state": "received", "receivedAt": "2026-10-02T07:15:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ] } } } }, "400": { "description": "Bad Request. Codes: `idempotency_key_required`, `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `batch_too_large`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "ingest", "x-mikono-scopes": [ "dms:ingest" ], "x-mikono-idempotency": "required" } }, "/dms/{system}/files": { "post": { "operationId": "postDmsFile", "summary": "Send a DMS file", "description": "Send one file of DMS documents as `application/xml`, or as `multipart/form-data` with exactly one file part. In the canonical format the root is `` with one `` per document; its child elements carry the canonical document's fields by name (header fields, then ``; a list is a container element with one child per item, for example `…`). Numbers are plain decimals and dates `YYYY-MM-DD`; elements Mikono does not know are ignored. DTDs and entity declarations are refused. The file is stored, deduplicated by SHA-256 (a file sent again returns its first batch with `duplicate: true` and is not processed again; a file whose batch was rejected can be sent again and is processed as a new batch), and read in the background; the answer is `202` with the batch id. Name the file with the part's filename or an `X-File-Name` header. Read the result at `GET /dms/{system}/files/{batchId}/flags`. At most 1,000 documents per file; raw files are kept 90 days.", "tags": [ "DMS" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "The partner system of your DMS connection: `canonical` (Mikono's own format) today; `edge365` once EABL's format is mapped.", "examples": [ "canonical" ] } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The file. At most 5 MB (`413 payload_too_large` above); another media type gets `415 unsupported_media_type`.", "content": { "application/xml": { "schema": { "type": "string", "contentMediaType": "application/xml" }, "example": "\n\n \n CSKBDVSM001000123\n KBD001\n 2026-09-25\n Confirmed\n KBDVSM001\n UG0000101\n UGX\n 30000\n \n cash\n \n \n 100231\n 10\n CS\n 3000\n selling\n \n \n \n \n\n" }, "text/xml": { "schema": { "type": "string", "contentMediaType": "text/xml" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "contentMediaType": "application/xml", "description": "The file. Exactly one file part." } }, "required": [ "file" ] }, "encoding": { "file": { "contentType": "application/xml, text/xml" } } } } }, "responses": { "202": { "description": "Accepted: the file is stored and will be read in the background (or was received before: `duplicate: true`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmsFileAccepted" }, "example": { "batchId": "kn7cd8qz3x0v1a9sd2m4p6r8t05tz2bz", "status": "received", "duplicate": false, "fileName": "KBD001-2026-09-25.xml", "receivedAt": "2026-09-25T18:05:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `idempotency_key_required`, `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Content Too Large. Codes: `payload_too_large`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "Unsupported Media Type. Codes: `unsupported_media_type`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "ingest", "x-mikono-scopes": [ "dms:ingest" ], "x-mikono-idempotency": "required" } }, "/dms/{system}/files/{batchId}/flags": { "get": { "operationId": "getDmsFileFlags", "summary": "Get a file's flag file", "description": "The flag file of one file batch, as XML: one `` per document with its current state (`received`, `posted`, `rejected` with a reason code R01–R09 and the reason, or `superseded`). Read it again later: documents move from `received` to `posted` or `rejected` as they post. A file that could not be read at all has one file-level flag (`level=\"file\"`) with the reason. When your connection returns flags by file, reading it marks the flags as returned.", "tags": [ "DMS" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "The partner system of your DMS connection: `canonical` (Mikono's own format) today; `edge365` once EABL's format is mapped.", "examples": [ "canonical" ] } }, { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "description": "The `batchId` from `POST /dms/{system}/files`." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/xml": { "schema": { "$ref": "#/components/schemas/DmsFlagFile" }, "example": "\n\n \n Customer UG0001234 is not known yet\n\n" } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "dms:flags:read" ], "x-mikono-idempotency": "none" } }, "/dms/{system}/flags": { "get": { "operationId": "listDmsFlags", "summary": "Read DMS update flags", "description": "The update flags of the documents you sent, oldest change first. Pass `since` (the last `updatedAt` you saw) to read only what changed, and `state` for one state. Each document appears once, with its current flag.\n\nWhen the connection returns flags in the response (`flagReturn: response`), the flags a call returns are recorded as returned to you. When flags go back by callback or flag file, reading them here marks nothing.", "tags": [ "DMS" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "The partner system the documents come from: `canonical` (Mikono's own JSON) today; `edge365` once EABL's format is mapped (planned). It must match an enabled DMS connection of your organisation.", "examples": [ "canonical" ] } }, { "name": "since", "in": "query", "required": false, "description": "Only flags that changed after this time. Store the last `updatedAt` you saw and pass it next time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "state", "in": "query", "required": false, "description": "Only flags in this state.", "schema": { "type": "string", "enum": [ "received", "posted", "rejected", "superseded" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's `nextCursor`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Default 50, maximum 200.", "schema": { "type": "number", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmsFlagPage" }, "example": { "data": [ { "documentId": "k57a2b3c4d5e6f7g8h9j0k1m2n3p4q5r", "distributorCode": "KBD001", "documentType": "sale_invoice", "documentNumber": "CSKBDVSM001000123", "state": "posted", "receivedAt": "2026-10-02T07:15:00.000Z", "updatedAt": "2026-10-02T07:16:30.000Z", "mikonoRef": { "table": "invoices", "id": "j97b0c1d2e3f4g5h6j7k8m9n0p1q2r3s" }, "quickbooksRef": "Invoice:1043", "postedAt": "2026-10-02T07:16:30.000Z" } ], "nextCursor": null, "hasMore": false } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "ingest", "x-mikono-scopes": [ "dms:flags:read" ], "x-mikono-idempotency": "none" } }, "/empties-movements": { "get": { "operationId": "listEmptiesMovements", "summary": "List empties movements", "description": "Returnable containers loaded, collected, issued and returned. Filtering by `tripId` needs `trips:read` as well as `stock:read`.", "tags": [ "Stock" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "customerId", "in": "query", "required": false, "description": "Only this customer's empties.", "schema": { "type": "string" } }, { "name": "tripId", "in": "query", "required": false, "description": "Only this trip's empties. Needs `trips:read` as well.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptiesMovementPage" }, "example": { "data": [ { "id": "kv77r9t1v3x5z7b9d1f3h5k7m9p1r3t5", "container": { "id": "kd79e1g3j5l7n9q1s3u5w7y9a1c3e5g7", "name": "Empty bottle 500ml (returnable)", "sku": "KBD-EMB-500", "dmsCode": null }, "type": "collected_at_stop", "quantity": 75, "customerId": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "stopId": "kp75z7b9d1f3h5k7m9p1r3t5v7x9z1b3", "notes": null, "createdAt": "2026-10-02T07:08:00.000Z", "updatedAt": "2026-10-02T07:08:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "stock:read" ], "x-mikono-idempotency": "none" } }, "/health": { "get": { "operationId": "getHealth", "summary": "Check the API is up", "description": "Needs no key. Use it for uptime checks and to read the deployment's environment and API version.", "tags": [ "System" ], "security": [], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "example": { "status": "ok", "version": "1.13.0", "environment": "test", "time": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `key_in_query`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service Unavailable. Codes: `unavailable`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [], "x-mikono-idempotency": "none" } }, "/invoices": { "get": { "operationId": "listInvoices", "summary": "List invoices", "description": "Newest first, or oldest change first with `updatedSince` (a resumable change feed: a write can become visible a few seconds after its `updatedAt`, so poll from your last checkpoint minus 5 minutes and skip records whose id and `updatedAt` you already processed). Filters run on each page, so a page can hold fewer than `limit` records while `hasMore` is true. A payment or credit note applied to an invoice changes its `balanceDue` and moves its `updatedAt`, so the feed returns it again. QuickBooks posting changes do not move `updatedAt`. The embedded customer's phone and TIN need `customers:pii`.", "tags": [ "Invoices" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "status", "in": "query", "required": false, "description": "Only invoices with this status.", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "required": false, "description": "Only documents of the customer with this Mikono id.", "schema": { "type": "string" } }, { "name": "businessDate", "in": "query", "required": false, "description": "Only invoices issued on this date.", "schema": { "type": "string", "format": "date" } }, { "name": "issueDateFrom", "in": "query", "required": false, "description": "Only invoices issued on or after this date.", "schema": { "type": "string", "format": "date" } }, { "name": "issueDateTo", "in": "query", "required": false, "description": "Only invoices issued on or before this date.", "schema": { "type": "string", "format": "date" } }, { "name": "tripId", "in": "query", "required": false, "description": "Only invoices made on this delivery trip.", "schema": { "type": "string" } }, { "name": "locationId", "in": "query", "required": false, "description": "Only invoices fulfilled from this warehouse or van.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePage" }, "example": { "data": [ { "id": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "invoiceNumber": "INV-000412", "status": "paid", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "issueDate": "2026-10-02", "dueDate": "2026-10-02", "salesOrderId": "jd71t3v5x7z9b1d3f5h7k9m1p3r5t7v9", "locationId": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "salespersonId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "paymentType": "cash", "pricesIncludeTax": true, "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "code": "780256", "name": "Tusker Lager 500ml" }, "description": "Tusker Lager 500ml", "quantity": 50, "unit": "bottle", "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "22881.36", "currency": "UGX" }, "amount": { "amount": "150000.00", "currency": "UGX" }, "type": "selling" }, { "product": { "id": "kd72r4t6v8x0z2b4d6f8h0k2m4p6r8t0", "code": "780116", "name": "Bell Lager 500ml" }, "description": "Bell Lager 500ml", "quantity": 25, "unit": "bottle", "unitPrice": { "amount": "2800.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "10677.97", "currency": "UGX" }, "amount": { "amount": "70000.00", "currency": "UGX" }, "type": "selling" } ], "linesTruncated": false, "subtotal": { "amount": "220000.00", "currency": "UGX" }, "discountAmount": { "amount": "0.00", "currency": "UGX" }, "taxAmount": { "amount": "33559.33", "currency": "UGX" }, "totalAmount": { "amount": "220000.00", "currency": "UGX" }, "balanceDue": { "amount": "0.00", "currency": "UGX" }, "currency": "UGX", "notes": null, "fiscal": { "status": null, "fdn": null, "verificationCode": null, "qrCode": null, "fiscalisedAt": null }, "posting": { "status": "posted", "quickbooksRef": "1043", "quickbooksType": "Invoice", "reason": null }, "externalCodes": { "dms": "CSKBDVSM001000412", "quickbooks": "1043" }, "createdAt": "2026-10-02T07:06:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "invoices:read" ], "x-mikono-idempotency": "none" }, "post": { "operationId": "createInvoice", "summary": "Create an invoice (van sale or warehouse sale)", "description": "Creates and posts an invoice through the Go van-sale core: revenue and VAT, stock out of `locationId`, cost of sales, container empties, the QuickBooks posting queue and EFRIS. The invoice is a sale on credit, so the customer's credit must cover it as Go checks it (approved for credit, not on hold, open balance plus this invoice within the limit), else `422 credit_limit_exceeded`. When `locationId` is a van this is a van sale with Go's rules: the Sales, Field sales and Inventory modules must be on (`422 field_sales_disabled`), the salesperson must be on an in-transit trip with that van for `issueDate` (else `422 no_open_trip`), the products must be on the trip's manifest within its balance, and the sale is recorded for the salesperson's DMS day. The invoice is left open for payment (`POST /payments`). A retry with the same `Idempotency-Key` returns the same invoice, and after the 24-hour key window the key still finds it. The document is posted at once, as Go's van sale is: API writes go through Mikono's server-side cores, which apply no amount-tiered approval. A reference inside the body that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field.", "tags": [ "Invoices" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceCreate" }, "example": { "customer": { "code": "UG2104417" }, "locationId": "j97b4m2x8c1v5n3q7w6e9r0t2y4u8i1o", "salespersonId": "jx7e5r8t1y4u7i0o3p6a9s2d5f8g1h4j", "issueDate": "2026-10-02", "pricesIncludeTax": true, "lines": [ { "product": { "code": "780116" }, "quantity": 2, "unit": "pack", "unitPrice": { "amount": "70000.00", "currency": "UGX" } } ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "jn7c2v6b1n9m3q8w4e7r2t5y0u6i1o3p", "invoiceNumber": "INV-000123", "status": "sent", "customer": { "id": "k171w2qv0x3r8m7s5d2c9b4n6h7m3p1a", "name": "Kisementi Bar", "code": "UG2104417" }, "issueDate": "2026-10-02", "dueDate": "2026-10-02", "salesOrderId": null, "locationId": "j97b4m2x8c1v5n3q7w6e9r0t2y4u8i1o", "tripId": "k97d3f6g9h2j5k8l1z4x7c0v3b6n9m2q", "salespersonId": "jx7e5r8t1y4u7i0o3p6a9s2d5f8g1h4j", "paymentType": null, "pricesIncludeTax": true, "lines": [ { "product": { "id": "k572a9b8c7d6e5f4g3h2j1k0m9n8p7q6", "code": "780116", "name": "Bell Lager 500ml" }, "description": "Bell Lager 500ml", "type": "selling", "quantity": 50, "unit": "bottle", "unitPrice": { "amount": "2372.88", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "21355.93", "currency": "UGX" }, "amount": { "amount": "118644.07", "currency": "UGX" } } ], "linesTruncated": false, "subtotal": { "amount": "118644.07", "currency": "UGX" }, "discountAmount": { "amount": "0.00", "currency": "UGX" }, "taxAmount": { "amount": "21355.93", "currency": "UGX" }, "totalAmount": { "amount": "140000.00", "currency": "UGX" }, "balanceDue": { "amount": "140000.00", "currency": "UGX" }, "currency": "UGX", "notes": null, "fiscal": { "status": null, "fdn": null, "verificationCode": null, "qrCode": null, "fiscalisedAt": null }, "posting": { "status": "pending", "quickbooksRef": null, "quickbooksType": null, "reason": null }, "externalCodes": {}, "createdAt": "2026-10-02T09:15:00.000Z", "updatedAt": "2026-10-02T09:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `idempotency_key_required`, `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `credit_limit_exceeded`, `customer_not_found`, `field_sales_disabled`, `idempotency_key_reused`, `insufficient_stock`, `location_not_found`, `no_open_trip`, `period_closed`, `product_not_found`, `user_not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "invoices:write" ], "x-mikono-idempotency": "required" } }, "/invoices/by-code/{system}/{code}": { "get": { "operationId": "getInvoiceByCode", "summary": "Get an invoice by external code", "description": "`GET /invoices/by-code/dms/CS000123` finds the invoice with that DMS invoice number.", "tags": [ "Invoices" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "Code system: `dms` or a registered partner system (`edge365`).", "examples": [ "dms" ] } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The record's code in that system: trimmed, case-sensitive, at most 64 characters.", "examples": [ "UG2000123" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "invoiceNumber": "INV-000412", "status": "paid", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "issueDate": "2026-10-02", "dueDate": "2026-10-02", "salesOrderId": "jd71t3v5x7z9b1d3f5h7k9m1p3r5t7v9", "locationId": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "salespersonId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "paymentType": "cash", "pricesIncludeTax": true, "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "code": "780256", "name": "Tusker Lager 500ml" }, "description": "Tusker Lager 500ml", "quantity": 50, "unit": "bottle", "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "22881.36", "currency": "UGX" }, "amount": { "amount": "150000.00", "currency": "UGX" }, "type": "selling" }, { "product": { "id": "kd72r4t6v8x0z2b4d6f8h0k2m4p6r8t0", "code": "780116", "name": "Bell Lager 500ml" }, "description": "Bell Lager 500ml", "quantity": 25, "unit": "bottle", "unitPrice": { "amount": "2800.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "10677.97", "currency": "UGX" }, "amount": { "amount": "70000.00", "currency": "UGX" }, "type": "selling" } ], "linesTruncated": false, "subtotal": { "amount": "220000.00", "currency": "UGX" }, "discountAmount": { "amount": "0.00", "currency": "UGX" }, "taxAmount": { "amount": "33559.33", "currency": "UGX" }, "totalAmount": { "amount": "220000.00", "currency": "UGX" }, "balanceDue": { "amount": "0.00", "currency": "UGX" }, "currency": "UGX", "notes": null, "fiscal": { "status": null, "fdn": null, "verificationCode": null, "qrCode": null, "fiscalisedAt": null }, "posting": { "status": "posted", "quickbooksRef": "1043", "quickbooksType": "Invoice", "reason": null }, "externalCodes": { "dms": "CSKBDVSM001000412", "quickbooks": "1043" }, "createdAt": "2026-10-02T07:06:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "invoices:read" ], "x-mikono-idempotency": "none" } }, "/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Get an invoice", "description": "With lines, EFRIS fiscal status (FDN) and QuickBooks posting status.", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "invoiceNumber": "INV-000412", "status": "paid", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "issueDate": "2026-10-02", "dueDate": "2026-10-02", "salesOrderId": "jd71t3v5x7z9b1d3f5h7k9m1p3r5t7v9", "locationId": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "salespersonId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "paymentType": "cash", "pricesIncludeTax": true, "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "code": "780256", "name": "Tusker Lager 500ml" }, "description": "Tusker Lager 500ml", "quantity": 50, "unit": "bottle", "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "22881.36", "currency": "UGX" }, "amount": { "amount": "150000.00", "currency": "UGX" }, "type": "selling" }, { "product": { "id": "kd72r4t6v8x0z2b4d6f8h0k2m4p6r8t0", "code": "780116", "name": "Bell Lager 500ml" }, "description": "Bell Lager 500ml", "quantity": 25, "unit": "bottle", "unitPrice": { "amount": "2800.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "10677.97", "currency": "UGX" }, "amount": { "amount": "70000.00", "currency": "UGX" }, "type": "selling" } ], "linesTruncated": false, "subtotal": { "amount": "220000.00", "currency": "UGX" }, "discountAmount": { "amount": "0.00", "currency": "UGX" }, "taxAmount": { "amount": "33559.33", "currency": "UGX" }, "totalAmount": { "amount": "220000.00", "currency": "UGX" }, "balanceDue": { "amount": "0.00", "currency": "UGX" }, "currency": "UGX", "notes": null, "fiscal": { "status": null, "fdn": null, "verificationCode": null, "qrCode": null, "fiscalisedAt": null }, "posting": { "status": "posted", "quickbooksRef": "1043", "quickbooksType": "Invoice", "reason": null }, "externalCodes": { "dms": "CSKBDVSM001000412", "quickbooks": "1043" }, "createdAt": "2026-10-02T07:06:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "invoices:read" ], "x-mikono-idempotency": "none" } }, "/invoices/{id}/void": { "post": { "operationId": "voidInvoice", "summary": "Void an invoice", "description": "Voids a posted invoice the way Mikono's Void invoice does: the revenue journal and cost of sales are reversed and the stock goes back to its location; the invoice keeps its number with nothing due. A paid, draft or already voided invoice is `409 invalid_state`; one with an EFRIS fiscal document cannot be voided here. Needs the Finance module. A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`.", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this operation; same semantics as on creates.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceVoid" }, "example": { "reason": "Keyed against the wrong outlet" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "jn7c2v6b1n9m3q8w4e7r2t5y0u6i1o3p", "invoiceNumber": "INV-000123", "status": "voided", "customer": { "id": "k171w2qv0x3r8m7s5d2c9b4n6h7m3p1a", "name": "Kisementi Bar", "code": "UG2104417" }, "issueDate": "2026-10-02", "dueDate": "2026-10-02", "salesOrderId": null, "locationId": "j97b4m2x8c1v5n3q7w6e9r0t2y4u8i1o", "tripId": "k97d3f6g9h2j5k8l1z4x7c0v3b6n9m2q", "salespersonId": "jx7e5r8t1y4u7i0o3p6a9s2d5f8g1h4j", "paymentType": null, "pricesIncludeTax": true, "lines": [ { "product": { "id": "k572a9b8c7d6e5f4g3h2j1k0m9n8p7q6", "code": "780116", "name": "Bell Lager 500ml" }, "description": "Bell Lager 500ml", "type": "selling", "quantity": 50, "unit": "bottle", "unitPrice": { "amount": "2372.88", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "21355.93", "currency": "UGX" }, "amount": { "amount": "118644.07", "currency": "UGX" } } ], "linesTruncated": false, "subtotal": { "amount": "118644.07", "currency": "UGX" }, "discountAmount": { "amount": "0.00", "currency": "UGX" }, "taxAmount": { "amount": "21355.93", "currency": "UGX" }, "totalAmount": { "amount": "140000.00", "currency": "UGX" }, "balanceDue": { "amount": "0.00", "currency": "UGX" }, "currency": "UGX", "notes": null, "fiscal": { "status": null, "fdn": null, "verificationCode": null, "qrCode": null, "fiscalisedAt": null }, "posting": { "status": "pending", "quickbooksRef": null, "quickbooksType": null, "reason": null }, "externalCodes": {}, "createdAt": "2026-10-02T09:15:00.000Z", "updatedAt": "2026-10-02T09:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`, `module_disabled`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`, `invalid_state`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `idempotency_key_reused`, `period_closed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "invoices:write" ], "x-mikono-idempotency": "optional" } }, "/journey-plans": { "get": { "operationId": "listJourneyPlans", "summary": "List journey plans", "description": "One plan per active route: the outlets visited on each weekday. `routeCode` returns one route's plan; `week` (a Monday) dates each day and keeps only the stops due that date.", "tags": [ "Routes" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "routeCode", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "week", "in": "query", "required": false, "description": "A Monday, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyPlanPage" }, "example": { "data": [ { "routeId": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "routeCode": "KBDVSM001", "week": "2026-W40", "days": [ { "day": "Fri", "date": "2026-10-02", "outlets": [ { "customerId": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "outletCode": "UG2104417", "sequence": 1, "frequency": "weekly" }, { "customerId": "jx7b2d4f6h8k0m2p4r6t8v0x2z4b6d8f", "outletCode": "UG2106348", "sequence": 2, "frequency": "weekly" } ] } ], "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "routes:read" ], "x-mikono-idempotency": "none" }, "put": { "operationId": "upsertJourneyPlan", "summary": "Replace a route's journey plan", "description": "The DMS route plan: days, each with its outlets in visit order. Replaces the route's outlet list; each outlet is visited weekly on the days it appears. A reference inside the request body (an outlet, product or route code or id) that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field.", "tags": [ "Routes" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this operation; same semantics as on creates.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyPlanUpsert" }, "example": { "routeCode": "KBDVSM001", "days": [ { "day": "Mon", "outlets": [ { "outletCode": "UG2000123", "sequence": 1 } ] } ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyPlan" }, "example": { "routeId": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "routeCode": "KBDVSM001", "week": "2026-W40", "days": [ { "day": "Fri", "date": "2026-10-02", "outlets": [ { "customerId": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "outletCode": "UG2104417", "sequence": 1, "frequency": "weekly" }, { "customerId": "jx7b2d4f6h8k0m2p4r6t8v0x2z4b6d8f", "outletCode": "UG2106348", "sequence": 2, "frequency": "weekly" } ] } ], "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `customer_not_found`, `idempotency_key_reused`, `route_not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "routes:write" ], "x-mikono-idempotency": "optional" } }, "/locations": { "get": { "operationId": "listLocations", "summary": "List warehouses and vans", "tags": [ "Locations" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "type", "in": "query", "required": false, "description": "`van` is a delivery truck.", "schema": { "type": "string", "enum": [ "warehouse", "van", "damages", "other" ] } }, { "name": "isActive", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationPage" }, "example": { "data": [ { "id": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "name": "Truck UBC 512K", "type": "van", "description": "Delivery truck for beats KBDVSM001 and KBDVSM003", "vehicleRegistration": "UBC 512K", "capacity": { "value": 40000, "unit": "units" }, "homeWarehouseId": "kh74c6e8g0j2l4n6q8s0u2w4y6a8c0e2", "isActive": true, "isDefault": false, "address": null, "externalCodes": { "dms": "UBC512K" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "locations:read" ], "x-mikono-idempotency": "none" } }, "/locations/by-code/{system}/{code}": { "get": { "operationId": "getLocationByCode", "summary": "Get a warehouse or van by code", "description": "A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`.", "tags": [ "Locations" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "Code system: `dms` or a registered partner system (`edge365`).", "examples": [ "dms" ] } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The record's code in that system: trimmed, case-sensitive, at most 64 characters.", "examples": [ "UG2000123" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" }, "example": { "id": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "name": "Truck UBC 512K", "type": "van", "description": "Delivery truck for beats KBDVSM001 and KBDVSM003", "vehicleRegistration": "UBC 512K", "capacity": { "value": 40000, "unit": "units" }, "homeWarehouseId": "kh74c6e8g0j2l4n6q8s0u2w4y6a8c0e2", "isActive": true, "isDefault": false, "address": null, "externalCodes": { "dms": "UBC512K" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "locations:read" ], "x-mikono-idempotency": "none" }, "put": { "operationId": "upsertLocationByCode", "summary": "Create or update a warehouse or van by code", "description": "Needs `stock:write` (which carries Manage Locations). A reference inside the request body (an outlet, product or route code or id) that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field.", "tags": [ "Locations" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "Code system: `dms` or a registered partner system (`edge365`).", "examples": [ "dms" ] } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The record's code in that system: trimmed, case-sensitive, at most 64 characters.", "examples": [ "UG2000123" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this operation; same semantics as on creates.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationUpsert" }, "example": { "name": "Van UBL 123X", "type": "van", "vehicleRegistration": "UBL 123X" } } } }, "responses": { "200": { "description": "Updated; 201 when created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" }, "example": { "id": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "name": "Truck UBC 512K", "type": "van", "description": "Delivery truck for beats KBDVSM001 and KBDVSM003", "vehicleRegistration": "UBC 512K", "capacity": { "value": 40000, "unit": "units" }, "homeWarehouseId": "kh74c6e8g0j2l4n6q8s0u2w4y6a8c0e2", "isActive": true, "isDefault": false, "address": null, "externalCodes": { "dms": "UBC512K" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `code_conflict`, `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "stock:write" ], "x-mikono-idempotency": "optional" } }, "/locations/{id}": { "get": { "operationId": "getLocation", "summary": "Get a warehouse or van", "description": "A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`.", "tags": [ "Locations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" }, "example": { "id": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "name": "Truck UBC 512K", "type": "van", "description": "Delivery truck for beats KBDVSM001 and KBDVSM003", "vehicleRegistration": "UBC 512K", "capacity": { "value": 40000, "unit": "units" }, "homeWarehouseId": "kh74c6e8g0j2l4n6q8s0u2w4y6a8c0e2", "isActive": true, "isDefault": false, "address": null, "externalCodes": { "dms": "UBC512K" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "locations:read" ], "x-mikono-idempotency": "none" } }, "/me": { "get": { "operationId": "getMe", "summary": "Describe the calling key", "description": "Any valid key may call this. Returns the key's name, environment, organisation, scopes and rate limits.", "tags": [ "System" ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" }, "example": { "name": "DMS bridge", "prefix": "mk_test_Ab12", "environment": "test", "organization": { "id": "wd709syv07f98c6w68x1eg6h058femh2", "name": "Kampala Beverage Distributors (Demo)" }, "scopes": [ "customers:read", "invoices:read" ], "rateLimits": { "read": { "perMinute": 600, "burst": 100 }, "write": { "perMinute": 120, "burst": 30 }, "ingest": { "perMinute": 60, "burst": 60 } } } } } }, "400": { "description": "Bad Request. Codes: `key_in_query`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [], "x-mikono-idempotency": "none" } }, "/openapi.json": { "get": { "operationId": "getOpenApiDocument", "summary": "Get this OpenAPI document", "description": "Needs no key. The same document is checked into the repository and mirrored on the developer docs.", "tags": [ "System" ], "security": [], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" }, "example": { "openapi": "3.1.0", "info": { "title": "Mikono API", "version": "1.13.0" }, "servers": [ { "url": "https://calculating-gnu-991.convex.site/api/v1", "description": "Sandbox (mk_test_ keys)" } ], "paths": { "/customers": { "get": { "operationId": "listCustomers", "summary": "List customers" } } } } } } }, "400": { "description": "Bad Request. Codes: `key_in_query`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [], "x-mikono-idempotency": "none" } }, "/orders": { "get": { "operationId": "listOrders", "summary": "List sales orders", "description": "Newest first, or oldest change first with `updatedSince` (a resumable change feed: a write can become visible a few seconds after its `updatedAt`, so poll from your last checkpoint minus 5 minutes and skip records whose id and `updatedAt` you already processed). Filters run on each page, so a page can hold fewer than `limit` records while `hasMore` is true. The embedded customer's phone and TIN need `customers:pii`.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "status", "in": "query", "required": false, "description": "Only orders with this status.", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "required": false, "description": "Only documents of the customer with this Mikono id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPage" }, "example": { "data": [ { "id": "jd71t3v5x7z9b1d3f5h7k9m1p3r5t7v9", "orderNumber": "SO-000207", "status": "invoiced", "source": "go", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "orderDate": "2026-10-02", "deliveryDate": "2026-10-02", "assignedRepId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "code": "780256", "name": "Tusker Lager 500ml" }, "description": "Tusker Lager 500ml", "quantity": 50, "unit": "bottle", "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "22881.36", "currency": "UGX" }, "amount": { "amount": "150000.00", "currency": "UGX" } }, { "product": { "id": "kd72r4t6v8x0z2b4d6f8h0k2m4p6r8t0", "code": "780116", "name": "Bell Lager 500ml" }, "description": "Bell Lager 500ml", "quantity": 25, "unit": "bottle", "unitPrice": { "amount": "2800.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "10677.97", "currency": "UGX" }, "amount": { "amount": "70000.00", "currency": "UGX" } } ], "linesTruncated": false, "subtotal": { "amount": "220000.00", "currency": "UGX" }, "discountAmount": { "amount": "0.00", "currency": "UGX" }, "taxAmount": { "amount": "33559.33", "currency": "UGX" }, "shippingAmount": { "amount": "0.00", "currency": "UGX" }, "totalAmount": { "amount": "220000.00", "currency": "UGX" }, "currency": "UGX", "notes": null, "invoiceId": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "externalCodes": { "dms": "SOKBDVSM001000207" }, "createdAt": "2026-10-02T07:05:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "orders:read" ], "x-mikono-idempotency": "none" }, "post": { "operationId": "createOrder", "summary": "Create a sales order", "description": "Creates a confirmed order through Mikono's sales order core, with `source: \"api\"`. Name the customer and each product by `id` or DMS `code`; `case` quantities are converted to base units with the product's pack size. Without `unitPrice`, a line takes the customer's price-group price. Tax and totals come from each product's tax rate. With `externalCodes.dms` (the RSS order number), a second create with that number returns the first order (200). A reference inside the request body (an outlet, product or route code or id) that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field. API writes run the same core as the Mikono app, attributed to the key's service actor, with an audit row (source Integration). Amount-tiered approval does not apply: the document is posted, not left for approval.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" }, "example": { "customer": { "code": "UG2104417" }, "deliveryDate": "2026-10-03", "lines": [ { "product": { "code": "780256" }, "quantity": 2, "unit": "case" } ], "externalCodes": { "dms": "RSS000123" } } } } }, "responses": { "201": { "description": "Created; 200 when the DMS number already has an order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": "kd7order000000000000000000000001", "orderNumber": "SO-2026-00123", "status": "confirmed", "source": "api", "customer": { "id": "kd7cust0000000000000000000000001", "name": "Mama Joy Shop, Ntinda", "code": "UG2104417" }, "orderDate": "2026-10-02", "deliveryDate": "2026-10-03", "assignedRepId": null, "lines": [ { "product": { "id": "kd7prod0000000000000000000000014", "code": "780256", "name": "Tusker Lager 500ml" }, "description": "Tusker Lager 500ml", "quantity": 50, "unit": "bottle", "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "27000.00", "currency": "UGX" }, "amount": { "amount": "177000.00", "currency": "UGX" } } ], "linesTruncated": false, "subtotal": { "amount": "150000.00", "currency": "UGX" }, "discountAmount": { "amount": "0.00", "currency": "UGX" }, "taxAmount": { "amount": "27000.00", "currency": "UGX" }, "shippingAmount": { "amount": "0.00", "currency": "UGX" }, "totalAmount": { "amount": "177000.00", "currency": "UGX" }, "currency": "UGX", "notes": null, "invoiceId": null, "externalCodes": { "dms": "RSS000123" }, "createdAt": "2026-10-02T07:15:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `idempotency_key_required`, `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `currency_mismatch`, `customer_not_found`, `idempotency_key_reused`, `product_not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "orders:write" ], "x-mikono-idempotency": "required" } }, "/orders/by-code/{system}/{code}": { "get": { "operationId": "getOrderByCode", "summary": "Get a sales order by external code", "description": "`GET /orders/by-code/dms/RSS000123` finds the order with that DMS order number.", "tags": [ "Orders" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "Code system: `dms` or a registered partner system (`edge365`).", "examples": [ "dms" ] } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The record's code in that system: trimmed, case-sensitive, at most 64 characters.", "examples": [ "UG2000123" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": "jd71t3v5x7z9b1d3f5h7k9m1p3r5t7v9", "orderNumber": "SO-000207", "status": "invoiced", "source": "go", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "orderDate": "2026-10-02", "deliveryDate": "2026-10-02", "assignedRepId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "code": "780256", "name": "Tusker Lager 500ml" }, "description": "Tusker Lager 500ml", "quantity": 50, "unit": "bottle", "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "22881.36", "currency": "UGX" }, "amount": { "amount": "150000.00", "currency": "UGX" } }, { "product": { "id": "kd72r4t6v8x0z2b4d6f8h0k2m4p6r8t0", "code": "780116", "name": "Bell Lager 500ml" }, "description": "Bell Lager 500ml", "quantity": 25, "unit": "bottle", "unitPrice": { "amount": "2800.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "10677.97", "currency": "UGX" }, "amount": { "amount": "70000.00", "currency": "UGX" } } ], "linesTruncated": false, "subtotal": { "amount": "220000.00", "currency": "UGX" }, "discountAmount": { "amount": "0.00", "currency": "UGX" }, "taxAmount": { "amount": "33559.33", "currency": "UGX" }, "shippingAmount": { "amount": "0.00", "currency": "UGX" }, "totalAmount": { "amount": "220000.00", "currency": "UGX" }, "currency": "UGX", "notes": null, "invoiceId": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "externalCodes": { "dms": "SOKBDVSM001000207" }, "createdAt": "2026-10-02T07:05:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "orders:read" ], "x-mikono-idempotency": "none" } }, "/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Get a sales order", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": "jd71t3v5x7z9b1d3f5h7k9m1p3r5t7v9", "orderNumber": "SO-000207", "status": "invoiced", "source": "go", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "orderDate": "2026-10-02", "deliveryDate": "2026-10-02", "assignedRepId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "code": "780256", "name": "Tusker Lager 500ml" }, "description": "Tusker Lager 500ml", "quantity": 50, "unit": "bottle", "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "22881.36", "currency": "UGX" }, "amount": { "amount": "150000.00", "currency": "UGX" } }, { "product": { "id": "kd72r4t6v8x0z2b4d6f8h0k2m4p6r8t0", "code": "780116", "name": "Bell Lager 500ml" }, "description": "Bell Lager 500ml", "quantity": 25, "unit": "bottle", "unitPrice": { "amount": "2800.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "10677.97", "currency": "UGX" }, "amount": { "amount": "70000.00", "currency": "UGX" } } ], "linesTruncated": false, "subtotal": { "amount": "220000.00", "currency": "UGX" }, "discountAmount": { "amount": "0.00", "currency": "UGX" }, "taxAmount": { "amount": "33559.33", "currency": "UGX" }, "shippingAmount": { "amount": "0.00", "currency": "UGX" }, "totalAmount": { "amount": "220000.00", "currency": "UGX" }, "currency": "UGX", "notes": null, "invoiceId": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "externalCodes": { "dms": "SOKBDVSM001000207" }, "createdAt": "2026-10-02T07:05:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "orders:read" ], "x-mikono-idempotency": "none" } }, "/orders/{id}/cancel": { "post": { "operationId": "cancelOrder", "summary": "Cancel a sales order", "description": "Cancels a draft or confirmed order through the cancel core Mikono Go uses: its trip stops are unlinked and the visit stays on the trip. An order that is already cancelled, delivered or invoiced, or whose stop has started, is `409 invalid_state`. `Idempotency-Key` is optional. A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`. API writes run the same core as the Mikono app, attributed to the key's service actor, with an audit row (source Integration). Amount-tiered approval does not apply: the document is posted, not left for approval.", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this operation; same semantics as on creates.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBody" }, "example": { "reason": "Outlet closed for renovation" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": "kd7order000000000000000000000001", "orderNumber": "SO-2026-00123", "status": "cancelled", "source": "api", "customer": { "id": "kd7cust0000000000000000000000001", "name": "Mama Joy Shop, Ntinda", "code": "UG2104417" }, "orderDate": "2026-10-02", "deliveryDate": "2026-10-03", "assignedRepId": null, "lines": [ { "product": { "id": "kd7prod0000000000000000000000014", "code": "780256", "name": "Tusker Lager 500ml" }, "description": "Tusker Lager 500ml", "quantity": 50, "unit": "bottle", "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "taxRate": 18, "tax": { "amount": "27000.00", "currency": "UGX" }, "amount": { "amount": "177000.00", "currency": "UGX" } } ], "linesTruncated": false, "subtotal": { "amount": "150000.00", "currency": "UGX" }, "discountAmount": { "amount": "0.00", "currency": "UGX" }, "taxAmount": { "amount": "27000.00", "currency": "UGX" }, "shippingAmount": { "amount": "0.00", "currency": "UGX" }, "totalAmount": { "amount": "177000.00", "currency": "UGX" }, "currency": "UGX", "notes": null, "invoiceId": null, "externalCodes": { "dms": "RSS000123" }, "createdAt": "2026-10-02T07:15:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`, `invalid_state`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "orders:write" ], "x-mikono-idempotency": "optional" } }, "/outlet-activities": { "get": { "operationId": "listOutletActivities", "summary": "List outlet reports", "description": "Competitor activity, stock photos, cooler checks, feedback and follow-ups recorded at outlets. `photoUrls` and `gps` appear only with `customers:pii`. Photo URLs are short-lived signed URLs: download the photo promptly and do not store the URL.", "tags": [ "Field activity" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "customerId", "in": "query", "required": false, "description": "Only this outlet's reports.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutletActivityPage" }, "example": { "data": [ { "id": "kx71v3x5z7b9d1f3h5k7m9p1r3t5v7x9", "customerId": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "kind": "cooler_check", "recordedBy": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "tripStopId": "kp75z7b9d1f3h5k7m9p1r3t5v7x9z1b3", "note": "Cooler full; asked for a second one.", "competitor": null, "stock": null, "cooler": { "present": true, "working": true, "ownBrandOnly": true, "branding": "Tusker", "issue": null }, "feedback": null, "followUp": null, "photoUrls": [ "https://calculating-gnu-991.convex.cloud/api/storage/3f2a9c1e-4b7d-4e8a-9c21-5d6e7f8a9b0c" ], "gps": { "latitude": 0.350849, "longitude": 32.612542 }, "capturedAt": "2026-10-02T07:10:00.000Z", "createdAt": "2026-10-02T07:10:00.000Z", "updatedAt": "2026-10-02T07:10:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "trips:read" ], "x-mikono-idempotency": "none" } }, "/payments": { "get": { "operationId": "listPayments", "summary": "List customer payments (collections)", "description": "Newest first, or oldest change first with `updatedSince` (a resumable change feed: a write can become visible a few seconds after its `updatedAt`, so poll from your last checkpoint minus 5 minutes and skip records whose id and `updatedAt` you already processed). Filters run on each page, so a page can hold fewer than `limit` records while `hasMore` is true. Vendor payments are not returned. The embedded customer's phone and TIN need `customers:pii`.", "tags": [ "Payments" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "customerId", "in": "query", "required": false, "description": "Only documents of the customer with this Mikono id.", "schema": { "type": "string" } }, { "name": "method", "in": "query", "required": false, "description": "Only payments by this method.", "schema": { "type": "string", "enum": [ "cash", "cheque", "mobile_money", "bank_transfer", "card", "other" ] } }, { "name": "paymentDateFrom", "in": "query", "required": false, "description": "Only payments dated on or after this date.", "schema": { "type": "string", "format": "date" } }, { "name": "paymentDateTo", "in": "query", "required": false, "description": "Only payments dated on or before this date.", "schema": { "type": "string", "format": "date" } }, { "name": "tripId", "in": "query", "required": false, "description": "Only collections made on this delivery trip.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPage" }, "example": { "data": [ { "id": "kn77d9f1h3k5m7p9r1t3v5x7z9b1d3f5", "paymentNumber": "PAY-000318", "status": "completed", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "paymentDate": "2026-10-02", "amount": { "amount": "214000.00", "currency": "UGX" }, "method": "cash", "reference": null, "cheque": null, "cleared": true, "salespersonId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "allocations": [ { "invoiceId": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "invoiceNumber": "INV-000412", "amount": { "amount": "214000.00", "currency": "UGX" } } ], "linesTruncated": false, "unallocated": { "amount": "0.00", "currency": "UGX" }, "unallocatedUnavailable": null, "currency": "UGX", "notes": null, "posting": { "status": "posted", "quickbooksRef": "884", "quickbooksType": "Payment", "reason": null }, "externalCodes": { "dms": "PYKBDVSM001000318", "quickbooks": "884" }, "createdAt": "2026-10-02T07:07:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "payments:read" ], "x-mikono-idempotency": "none" }, "post": { "operationId": "createPayment", "summary": "Record a customer payment (collection)", "description": "Records a collection the way Mikono Go does: one receipt per allocation through the receipt core (DR cash or the tender's clearing account, CR receivables), each queued for QuickBooks against its invoice. Cash lands in the organisation's cash account. The allocations must add up to `amount` (`422 over_allocation` / `unallocated_amount`) and fit each invoice's open balance (`422 over_allocation`); the payment, its allocations and the invoices share one currency (`422 currency_mismatch`). With `externalCodes.dms` (the PY number), a second create with that number returns the first receipts (200). A reference inside the request body (an outlet, product or route code or id) that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field. API writes run the same core as the Mikono app, attributed to the key's service actor, with an audit row (source Integration). Amount-tiered approval does not apply: the document is posted, not left for approval.", "tags": [ "Payments" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCreate" }, "example": { "customer": { "code": "UG2104417" }, "paymentDate": "2026-10-02", "amount": { "amount": "250000.00", "currency": "UGX" }, "method": "cash", "allocations": [ { "invoice": { "code": "CS000123" }, "amount": { "amount": "177000.00", "currency": "UGX" } }, { "invoice": { "code": "CS000124" }, "amount": { "amount": "73000.00", "currency": "UGX" } } ], "externalCodes": { "dms": "PY000123" } } } } }, "responses": { "201": { "description": "Created; 200 when the DMS number or this key's receipts already exist.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceipts" }, "example": { "payments": [ { "id": "kd7paym0000000000000000000000001", "paymentNumber": "PMT-INV-2026-0101-0001", "status": "recorded", "customer": { "id": "kd7cust0000000000000000000000001", "name": "Mama Joy Shop, Ntinda", "code": "UG2104417" }, "paymentDate": "2026-10-02", "amount": { "amount": "177000.00", "currency": "UGX" }, "method": "cash", "reference": null, "cheque": null, "cleared": false, "salespersonId": "kd7user0000000000000000000000api", "tripId": null, "allocations": [ { "invoiceId": "kd7invo0000000000000000000000001", "invoiceNumber": "INV-2026-0101", "amount": { "amount": "177000.00", "currency": "UGX" } } ], "linesTruncated": false, "unallocated": { "amount": "0.00", "currency": "UGX" }, "unallocatedUnavailable": null, "currency": "UGX", "notes": null, "posting": { "status": "pending", "quickbooksRef": null, "quickbooksType": null, "reason": null }, "externalCodes": { "dms": "PY000123" }, "createdAt": "2026-10-02T07:15:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" }, { "id": "kd7paym0000000000000000000000002", "paymentNumber": "PMT-INV-2026-0102-0001", "status": "recorded", "customer": { "id": "kd7cust0000000000000000000000001", "name": "Mama Joy Shop, Ntinda", "code": "UG2104417" }, "paymentDate": "2026-10-02", "amount": { "amount": "73000.00", "currency": "UGX" }, "method": "cash", "reference": null, "cheque": null, "cleared": false, "salespersonId": "kd7user0000000000000000000000api", "tripId": null, "allocations": [ { "invoiceId": "kd7invo0000000000000000000000002", "invoiceNumber": "INV-2026-0102", "amount": { "amount": "73000.00", "currency": "UGX" } } ], "linesTruncated": false, "unallocated": { "amount": "0.00", "currency": "UGX" }, "unallocatedUnavailable": null, "currency": "UGX", "notes": null, "posting": { "status": "pending", "quickbooksRef": null, "quickbooksType": null, "reason": null }, "externalCodes": { "dms": "PY000123" }, "createdAt": "2026-10-02T07:15:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ] } } } }, "400": { "description": "Bad Request. Codes: `idempotency_key_required`, `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `currency_mismatch`, `customer_not_found`, `idempotency_key_reused`, `invoice_not_found`, `over_allocation`, `period_closed`, `unallocated_amount`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "payments:write" ], "x-mikono-idempotency": "required" } }, "/payments/by-code/{system}/{code}": { "get": { "operationId": "getPaymentByCode", "summary": "Get a customer payment by external code", "description": "`GET /payments/by-code/dms/PY000123` finds the payment with that DMS payment number.", "tags": [ "Payments" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "Code system: `dms` or a registered partner system (`edge365`).", "examples": [ "dms" ] } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The record's code in that system: trimmed, case-sensitive, at most 64 characters.", "examples": [ "UG2000123" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "kn77d9f1h3k5m7p9r1t3v5x7z9b1d3f5", "paymentNumber": "PAY-000318", "status": "completed", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "paymentDate": "2026-10-02", "amount": { "amount": "214000.00", "currency": "UGX" }, "method": "cash", "reference": null, "cheque": null, "cleared": true, "salespersonId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "allocations": [ { "invoiceId": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "invoiceNumber": "INV-000412", "amount": { "amount": "214000.00", "currency": "UGX" } } ], "linesTruncated": false, "unallocated": { "amount": "0.00", "currency": "UGX" }, "unallocatedUnavailable": null, "currency": "UGX", "notes": null, "posting": { "status": "posted", "quickbooksRef": "884", "quickbooksType": "Payment", "reason": null }, "externalCodes": { "dms": "PYKBDVSM001000318", "quickbooks": "884" }, "createdAt": "2026-10-02T07:07:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "payments:read" ], "x-mikono-idempotency": "none" } }, "/payments/{id}": { "get": { "operationId": "getPayment", "summary": "Get a customer payment", "tags": [ "Payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "kn77d9f1h3k5m7p9r1t3v5x7z9b1d3f5", "paymentNumber": "PAY-000318", "status": "completed", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "paymentDate": "2026-10-02", "amount": { "amount": "214000.00", "currency": "UGX" }, "method": "cash", "reference": null, "cheque": null, "cleared": true, "salespersonId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "allocations": [ { "invoiceId": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "invoiceNumber": "INV-000412", "amount": { "amount": "214000.00", "currency": "UGX" } } ], "linesTruncated": false, "unallocated": { "amount": "0.00", "currency": "UGX" }, "unallocatedUnavailable": null, "currency": "UGX", "notes": null, "posting": { "status": "posted", "quickbooksRef": "884", "quickbooksType": "Payment", "reason": null }, "externalCodes": { "dms": "PYKBDVSM001000318", "quickbooks": "884" }, "createdAt": "2026-10-02T07:07:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "payments:read" ], "x-mikono-idempotency": "none" } }, "/payments/{id}/reverse": { "post": { "operationId": "reversePayment", "summary": "Reverse a customer payment", "description": "Voids one receipt through Mikono's payment void core: the invoice balance it settled is restored and a reversing journal is posted. Reverse each receipt of a multi-allocation payment. A receipt already reversed is `409 invalid_state`, and so is one QuickBooks holds or is about to post: Mikono cannot void a QuickBooks payment yet, so void it in QuickBooks and Mikono by hand. `Idempotency-Key` is optional. A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`. API writes run the same core as the Mikono app, attributed to the key's service actor, with an audit row (source Integration). Amount-tiered approval does not apply: the document is posted, not left for approval.", "tags": [ "Payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this operation; same semantics as on creates.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBody" }, "example": { "reason": "Cheque bounced" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "kd7paym0000000000000000000000001", "paymentNumber": "PMT-INV-2026-0101-0001", "status": "void", "customer": { "id": "kd7cust0000000000000000000000001", "name": "Mama Joy Shop, Ntinda", "code": "UG2104417" }, "paymentDate": "2026-10-02", "amount": { "amount": "177000.00", "currency": "UGX" }, "method": "cash", "reference": null, "cheque": null, "cleared": false, "salespersonId": "kd7user0000000000000000000000api", "tripId": null, "allocations": [ { "invoiceId": "kd7invo0000000000000000000000001", "invoiceNumber": "INV-2026-0101", "amount": { "amount": "177000.00", "currency": "UGX" } } ], "linesTruncated": false, "unallocated": { "amount": "0.00", "currency": "UGX" }, "unallocatedUnavailable": null, "currency": "UGX", "notes": null, "posting": { "status": "pending", "quickbooksRef": null, "quickbooksType": null, "reason": null }, "externalCodes": { "dms": "PY000123" }, "createdAt": "2026-10-02T07:15:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`, `invalid_state`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `idempotency_key_reused`, `period_closed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "payments:write" ], "x-mikono-idempotency": "optional" } }, "/prices": { "get": { "operationId": "listPrices", "summary": "List prices", "description": "One row per product, price group and unit. `externalCode=dms:` lists one product's prices.", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "priceGroup", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricePage" }, "example": { "data": [ { "id": "nb51a3c5e7g9j1l3n5q7s9u1w3y5a7c9", "productId": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "productCode": "780256", "priceGroup": "retail", "unit": "pack", "price": { "amount": "75000.00", "currency": "UGX" }, "minimumQuantity": null, "isDefault": true, "isActive": true, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "prices:read" ], "x-mikono-idempotency": "none" }, "put": { "operationId": "upsertPrices", "summary": "Create or update prices in bulk", "description": "Each price is keyed by product code, price group and unit. Every product code is checked before anything is written: one unknown code fails the whole request with `product_not_found` and `errors[]`. Mikono prices have no effective dates; `effectiveFrom` and `effectiveTo` are refused with `unknown_field`. A reference inside the request body (an outlet, product or route code or id) that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field.", "tags": [ "Products" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this operation; same semantics as on creates.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricesUpsert" }, "example": { "prices": [ { "productCode": "780123", "priceGroup": "hqrt", "unit": "pack", "price": { "amount": "62000.00", "currency": "UGX" } } ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricesUpsertResult" }, "example": { "data": [ { "id": "nb51a3c5e7g9j1l3n5q7s9u1w3y5a7c9", "productId": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "productCode": "780256", "priceGroup": "retail", "unit": "pack", "price": { "amount": "75000.00", "currency": "UGX" }, "minimumQuantity": null, "isDefault": true, "isActive": true, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "created": 0, "updated": 1, "unchanged": 0 } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `currency_not_found`, `idempotency_key_reused`, `product_not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "prices:write" ], "x-mikono-idempotency": "optional" } }, "/products": { "get": { "operationId": "listProducts", "summary": "List products", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "archived" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPage" }, "example": { "data": [ { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "name": "Tusker Lager 500ml", "description": null, "sku": "KBD-14", "barcode": null, "unit": "bottle", "packSize": 25, "packLabel": "Crate", "baseUnitLabel": "Bottle", "isReturnableContainer": false, "containers": [ { "productId": "kd79e1g3j5l7n9q1s3u5w7y9a1c3e5g7", "productCode": "KBD-EMB-500", "quantityPerUnit": 1 } ], "taxRate": 18, "priceIncludesVat": true, "price": { "amount": "3000.00", "currency": "UGX" }, "trackInventory": true, "status": "active", "category": "Beer", "brand": "Tusker", "externalCodes": { "dms": "780256" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "products:read" ], "x-mikono-idempotency": "none" } }, "/products/by-code/{system}/{code}": { "get": { "operationId": "getProductByCode", "summary": "Get a product by external code", "description": "A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`.", "tags": [ "Products" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "Code system: `dms` or a registered partner system (`edge365`).", "examples": [ "dms" ] } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The record's code in that system: trimmed, case-sensitive, at most 64 characters.", "examples": [ "UG2000123" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "name": "Tusker Lager 500ml", "description": null, "sku": "KBD-14", "barcode": null, "unit": "bottle", "packSize": 25, "packLabel": "Crate", "baseUnitLabel": "Bottle", "isReturnableContainer": false, "containers": [ { "productId": "kd79e1g3j5l7n9q1s3u5w7y9a1c3e5g7", "productCode": "KBD-EMB-500", "quantityPerUnit": 1 } ], "taxRate": 18, "priceIncludesVat": true, "price": { "amount": "3000.00", "currency": "UGX" }, "trackInventory": true, "status": "active", "category": "Beer", "brand": "Tusker", "externalCodes": { "dms": "780256" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "products:read" ], "x-mikono-idempotency": "none" }, "put": { "operationId": "upsertProductByCode", "summary": "Create or update a product by external code", "description": "Creates the product when no product has this code (201), else updates the fields sent (200). Only `dms` codes are writable. A reference inside the request body (an outlet, product or route code or id) that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field.", "tags": [ "Products" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "Code system: `dms` or a registered partner system (`edge365`).", "examples": [ "dms" ] } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The record's code in that system: trimmed, case-sensitive, at most 64 characters.", "examples": [ "UG2000123" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this operation; same semantics as on creates.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpsert" }, "example": { "name": "Nile Special 500ml", "packSize": 25, "packLabel": "Crate", "baseUnitLabel": "Bottle", "trackInventory": true } } } }, "responses": { "200": { "description": "Updated; 201 when created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "name": "Tusker Lager 500ml", "description": null, "sku": "KBD-14", "barcode": null, "unit": "bottle", "packSize": 25, "packLabel": "Crate", "baseUnitLabel": "Bottle", "isReturnableContainer": false, "containers": [ { "productId": "kd79e1g3j5l7n9q1s3u5w7y9a1c3e5g7", "productCode": "KBD-EMB-500", "quantityPerUnit": 1 } ], "taxRate": 18, "priceIncludesVat": true, "price": { "amount": "3000.00", "currency": "UGX" }, "trackInventory": true, "status": "active", "category": "Beer", "brand": "Tusker", "externalCodes": { "dms": "780256" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `code_conflict`, `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `currency_not_found`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "products:write" ], "x-mikono-idempotency": "optional" } }, "/products/{id}": { "get": { "operationId": "getProduct", "summary": "Get a product", "description": "A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`.", "tags": [ "Products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "name": "Tusker Lager 500ml", "description": null, "sku": "KBD-14", "barcode": null, "unit": "bottle", "packSize": 25, "packLabel": "Crate", "baseUnitLabel": "Bottle", "isReturnableContainer": false, "containers": [ { "productId": "kd79e1g3j5l7n9q1s3u5w7y9a1c3e5g7", "productCode": "KBD-EMB-500", "quantityPerUnit": 1 } ], "taxRate": 18, "priceIncludesVat": true, "price": { "amount": "3000.00", "currency": "UGX" }, "trackInventory": true, "status": "active", "category": "Beer", "brand": "Tusker", "externalCodes": { "dms": "780256" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "products:read" ], "x-mikono-idempotency": "none" } }, "/returns": { "get": { "operationId": "listReturns", "summary": "List returns", "description": "Newest first, or oldest change first with `updatedSince` (a resumable change feed: a write can become visible a few seconds after its `updatedAt`, so poll from your last checkpoint minus 5 minutes and skip records whose id and `updatedAt` you already processed). Filters run on each page, so a page can hold fewer than `limit` records while `hasMore` is true. DMS return numbers are not unique: `?externalCode=dms:RT…` lists every return carrying the number. The embedded customer's phone and TIN need `customers:pii`.", "tags": [ "Returns" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "status", "in": "query", "required": false, "description": "Only returns with this status.", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "required": false, "description": "Only documents of the customer with this Mikono id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnPage" }, "example": { "data": [ { "id": "kq73z5b7d9f1h3k5m7p9r1t3v5x7z9b1", "returnNumber": "RMA-000011", "status": "completed", "returnType": "refund", "reason": "damaged", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "source": { "type": "invoice", "id": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "number": "INV-000412" }, "requestedDate": "2026-10-02", "completedDate": "2026-10-02", "toLocationId": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "creditNoteId": "kz75b7d9f1h3k5m7p9r1t3v5x7z9b1d3", "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "code": "780256", "name": "Tusker Lager 500ml" }, "quantity": 2, "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "amount": { "amount": "6000.00", "currency": "UGX" }, "reasonCode": "damaged", "condition": "damaged", "restockable": false } ], "linesTruncated": false, "totalAmount": { "amount": "6000.00", "currency": "UGX" }, "refundAmount": { "amount": "0.00", "currency": "UGX" }, "currency": "UGX", "notes": "Two broken bottles found at delivery.", "externalCodes": {}, "createdAt": "2026-10-02T07:12:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "returns:read" ], "x-mikono-idempotency": "none" }, "post": { "operationId": "createReturn", "summary": "Record a customer return", "description": "Records goods back from a customer against the invoice they were sold on and processes it in one step: the return is `completed`, and a return credit note is issued at the invoice's price and VAT, applied to its open balance, with good goods back in stock at `toLocationId` at the cost they left at (damaged goods are credited, not restocked). Returnable containers are recorded as empties collected, as Go does at a stop. Goods and empties back on a van on its in-transit trip join that trip's returns. As at a Go stop, the credit note (not the return) is what posts to QuickBooks, with its VAT and the credit it applied; the return's `refundAmount` is 0 because no cash is refunded, and `creditNoteId` links the note. A credit against an invoice sold on a trip counts in that trip's settlement. The document is posted at once, as Go's van sale is: API writes go through Mikono's server-side cores, which apply no amount-tiered approval. A reference inside the body that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field.", "tags": [ "Returns" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnCreate" }, "example": { "customer": { "code": "UG2104417" }, "sourceInvoiceId": "jn7c2v6b1n9m3q8w4e7r2t5y0u6i1o3p", "toLocationId": "j97b4m2x8c1v5n3q7w6e9r0t2y4u8i1o", "reason": "Short-dated stock", "lines": [ { "product": { "code": "780116" }, "quantity": 6, "condition": "good" } ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Return" }, "example": { "id": "jr7a1s4d7f0g3h6j9k2l5z8x1c4v7b0n", "returnNumber": "RET-000012", "status": "completed", "returnType": "customer_return", "reason": "Short-dated stock", "customer": { "id": "k171w2qv0x3r8m7s5d2c9b4n6h7m3p1a", "name": "Kisementi Bar", "code": "UG2104417" }, "source": { "type": "invoice", "id": "jn7c2v6b1n9m3q8w4e7r2t5y0u6i1o3p", "number": "INV-000123" }, "requestedDate": "2026-10-02", "completedDate": "2026-10-02", "toLocationId": "j97b4m2x8c1v5n3q7w6e9r0t2y4u8i1o", "creditNoteId": "jc71m4n7b0v3c6x9z2l5k8j1h4g7f0d3", "lines": [ { "product": { "id": "k572a9b8c7d6e5f4g3h2j1k0m9n8p7q6", "code": "780116", "name": "Bell Lager 500ml" }, "quantity": 6, "unitPrice": { "amount": "2800.00", "currency": "UGX" }, "amount": { "amount": "16800.00", "currency": "UGX" }, "reasonCode": "Short-dated stock", "condition": "new", "restockable": true } ], "linesTruncated": false, "totalAmount": { "amount": "16800.00", "currency": "UGX" }, "refundAmount": { "amount": "0.00", "currency": "UGX" }, "currency": "UGX", "notes": null, "externalCodes": {}, "createdAt": "2026-10-02T11:00:00.000Z", "updatedAt": "2026-10-02T11:00:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `idempotency_key_required`, `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`, `invalid_state`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `currency_not_supported`, `customer_not_found`, `idempotency_key_reused`, `invoice_not_found`, `location_not_found`, `period_closed`, `product_not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "returns:write" ], "x-mikono-idempotency": "required" } }, "/returns/{id}": { "get": { "operationId": "getReturn", "summary": "Get a return", "tags": [ "Returns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Return" }, "example": { "id": "kq73z5b7d9f1h3k5m7p9r1t3v5x7z9b1", "returnNumber": "RMA-000011", "status": "completed", "returnType": "refund", "reason": "damaged", "customer": { "id": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "name": "Hilltop Sports Bar, Ntinda", "code": "UG2104417", "phone": "+256700001001", "taxId": null }, "source": { "type": "invoice", "id": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "number": "INV-000412" }, "requestedDate": "2026-10-02", "completedDate": "2026-10-02", "toLocationId": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "creditNoteId": "kz75b7d9f1h3k5m7p9r1t3v5x7z9b1d3", "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "code": "780256", "name": "Tusker Lager 500ml" }, "quantity": 2, "unitPrice": { "amount": "3000.00", "currency": "UGX" }, "amount": { "amount": "6000.00", "currency": "UGX" }, "reasonCode": "damaged", "condition": "damaged", "restockable": false } ], "linesTruncated": false, "totalAmount": { "amount": "6000.00", "currency": "UGX" }, "refundAmount": { "amount": "0.00", "currency": "UGX" }, "currency": "UGX", "notes": "Two broken bottles found at delivery.", "externalCodes": {}, "createdAt": "2026-10-02T07:12:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "returns:read" ], "x-mikono-idempotency": "none" } }, "/routes": { "get": { "operationId": "listRoutes", "summary": "List routes", "tags": [ "Routes" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "isActive", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "territory", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePage" }, "example": { "data": [ { "id": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "name": "KBDVSM001 · Ntinda – Naguru", "code": "KBDVSM001", "description": "Mon, Wed and Fri beat", "territory": "Ntinda", "visitType": "beer", "isActive": true, "defaultSalesRepId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "defaultDriverId": "jn7e6g8j0l2n4q6s8u0w2y4a6c8e0g2j", "defaultTruckLocationId": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "externalCodes": { "dms": "KBDVSM001" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "routes:read" ], "x-mikono-idempotency": "none" } }, "/routes/by-code/{system}/{code}": { "get": { "operationId": "getRouteByCode", "summary": "Get a route by code", "description": "A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`.", "tags": [ "Routes" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "Code system: `dms` or a registered partner system (`edge365`).", "examples": [ "dms" ] } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The record's code in that system: trimmed, case-sensitive, at most 64 characters.", "examples": [ "UG2000123" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Route" }, "example": { "id": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "name": "KBDVSM001 · Ntinda – Naguru", "code": "KBDVSM001", "description": "Mon, Wed and Fri beat", "territory": "Ntinda", "visitType": "beer", "isActive": true, "defaultSalesRepId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "defaultDriverId": "jn7e6g8j0l2n4q6s8u0w2y4a6c8e0g2j", "defaultTruckLocationId": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "externalCodes": { "dms": "KBDVSM001" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "routes:read" ], "x-mikono-idempotency": "none" }, "put": { "operationId": "upsertRouteByCode", "summary": "Create or update a route by code", "description": "A reference inside the request body (an outlet, product or route code or id) that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field.", "tags": [ "Routes" ], "parameters": [ { "name": "system", "in": "path", "required": true, "schema": { "type": "string", "description": "Code system: `dms` or a registered partner system (`edge365`).", "examples": [ "dms" ] } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The record's code in that system: trimmed, case-sensitive, at most 64 characters.", "examples": [ "UG2000123" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this operation; same semantics as on creates.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteUpsert" }, "example": { "name": "Ntinda beer beat", "territory": "Ntinda", "visitType": "beer" } } } }, "responses": { "200": { "description": "Updated; 201 when created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Route" }, "example": { "id": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "name": "KBDVSM001 · Ntinda – Naguru", "code": "KBDVSM001", "description": "Mon, Wed and Fri beat", "territory": "Ntinda", "visitType": "beer", "isActive": true, "defaultSalesRepId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "defaultDriverId": "jn7e6g8j0l2n4q6s8u0w2y4a6c8e0g2j", "defaultTruckLocationId": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "externalCodes": { "dms": "KBDVSM001" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `code_conflict`, `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `idempotency_key_reused`, `location_not_found`, `user_not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "routes:write" ], "x-mikono-idempotency": "optional" } }, "/routes/{id}": { "get": { "operationId": "getRoute", "summary": "Get a route", "description": "A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`.", "tags": [ "Routes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Route" }, "example": { "id": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "name": "KBDVSM001 · Ntinda – Naguru", "code": "KBDVSM001", "description": "Mon, Wed and Fri beat", "territory": "Ntinda", "visitType": "beer", "isActive": true, "defaultSalesRepId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "defaultDriverId": "jn7e6g8j0l2n4q6s8u0w2y4a6c8e0g2j", "defaultTruckLocationId": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "externalCodes": { "dms": "KBDVSM001" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "routes:read" ], "x-mikono-idempotency": "none" } }, "/routes/{id}/outlets": { "get": { "operationId": "getRouteOutlets", "summary": "Get a route's outlets", "description": "A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`.", "tags": [ "Routes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteOutlets" }, "example": { "routeId": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "routeCode": "KBDVSM001", "outlets": [ { "customerId": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "outletCode": "UG2104417", "sequence": 1, "isActive": true, "daysOfWeek": [ "Mon", "Wed", "Fri" ], "frequency": "weekly", "weekOfMonth": null, "anchorDate": null }, { "customerId": "jx7b2d4f6h8k0m2p4r6t8v0x2z4b6d8f", "outletCode": "UG2106348", "sequence": 2, "isActive": true, "daysOfWeek": [ "Mon", "Wed", "Fri" ], "frequency": "weekly", "weekOfMonth": null, "anchorDate": null } ] } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "routes:read" ], "x-mikono-idempotency": "none" }, "put": { "operationId": "setRouteOutlets", "summary": "Replace a route's outlets", "description": "Replaces the whole list with the outlets sent, with their sequence and cadence. Outlets must be active. A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`. A reference inside the request body (an outlet, product or route code or id) that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field.", "tags": [ "Routes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this operation; same semantics as on creates.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteOutletsUpsert" }, "example": { "outlets": [ { "outletCode": "UG2000123", "sequence": 1, "daysOfWeek": [ "Mon", "Thu" ], "frequency": "weekly" } ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteOutlets" }, "example": { "routeId": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "routeCode": "KBDVSM001", "outlets": [ { "customerId": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "outletCode": "UG2104417", "sequence": 1, "isActive": true, "daysOfWeek": [ "Mon", "Wed", "Fri" ], "frequency": "weekly", "weekOfMonth": null, "anchorDate": null }, { "customerId": "jx7b2d4f6h8k0m2p4r6t8v0x2z4b6d8f", "outletCode": "UG2106348", "sequence": 2, "isActive": true, "daysOfWeek": [ "Mon", "Wed", "Fri" ], "frequency": "weekly", "weekOfMonth": null, "anchorDate": null } ] } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `customer_not_found`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "routes:write" ], "x-mikono-idempotency": "optional" } }, "/salespeople": { "get": { "operationId": "listSalespeople", "summary": "List salespeople", "description": "Members holding the salesperson persona. Read-only. `updatedAt` is the latest change to the membership, the person (name, phone, active), their route assignments, DMS logins or salesman-code links. With `updatedSince` the list is ordered by (`updatedAt`, `id`); it is available to organisations with at most 1,000 members (else `422 business_rule`). `externalCode=dms:` resolves DMS logins and `dms` links; any other system resolves only through that system's links.", "tags": [ "Routes" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalespersonPage" }, "example": { "data": [ { "id": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "name": "Brian Okello", "status": "active", "personas": [ "salesperson" ], "salesmanCode": "KBDVSM001", "defaultRouteId": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "phone": "+256700009001", "externalCodes": { "dms": "KBDVSM001" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "routes:read" ], "x-mikono-idempotency": "none" } }, "/salespeople/{id}": { "get": { "operationId": "getSalesperson", "summary": "Get a salesperson", "description": "A record in the path that does not exist, or belongs to another organisation, answers `404 not_found`.", "tags": [ "Routes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Salesperson" }, "example": { "id": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "name": "Brian Okello", "status": "active", "personas": [ "salesperson" ], "salesmanCode": "KBDVSM001", "defaultRouteId": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "phone": "+256700009001", "externalCodes": { "dms": "KBDVSM001" }, "createdAt": "2026-09-14T06:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "routes:read" ], "x-mikono-idempotency": "none" } }, "/settlements": { "get": { "operationId": "listSettlements", "summary": "List settlements", "description": "Full settlement sheets (the same body as `GET /trips/{id}/settlement`) of trips that are reconciling or closed. Mikono stores no settlement totals that equal the sheet to the shilling, so each sheet is computed from the trip's documents, one trip at a time: a page holds at most 5 (`limit` above 5 is lowered to 5); follow `nextCursor` while `hasMore`. With `updatedSince`, by the trip's `updatedAt` ascending; a trip's close updates it. `403 module_disabled` when the Delivery module is off.", "tags": [ "Trips" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "businessDate", "in": "query", "required": false, "description": "Settlements of trips planned for this business date.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripSettlementPage" }, "example": { "data": [ { "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "date": "2026-10-02", "status": "closed", "routeName": "KBDVSM001 · Ntinda – Naguru", "salesValue": { "amount": "3150000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "creditSales": { "amount": "0.00", "currency": "UGX" }, "nonCashCollections": { "amount": "420000.00", "currency": "UGX" }, "prepayments": { "amount": "0.00", "currency": "UGX" }, "debtCollectionsCash": { "amount": "0.00", "currency": "UGX" }, "creditNotes": { "amount": "6000.00", "currency": "UGX" }, "cashRefunds": { "amount": "0.00", "currency": "UGX" }, "cashExpenses": { "amount": "0.00", "currency": "UGX" }, "cashExpectedFromSales": { "amount": "2724000.00", "currency": "UGX" }, "floatIssued": { "amount": "50000.00", "currency": "UGX" }, "cashExpected": { "amount": "2774000.00", "currency": "UGX" }, "cashCounted": { "amount": "2774000.00", "currency": "UGX" }, "variance": { "amount": "0.00", "currency": "UGX" }, "varianceReason": null, "mobileMoney": { "amount": "420000.00", "currency": "UGX" }, "credit": { "amount": "0.00", "currency": "UGX" }, "collected": { "amount": "3194000.00", "currency": "UGX" }, "stockVarianceValue": { "amount": "0.00", "currency": "UGX" }, "stockReconciliation": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "name": "Tusker Lager 500ml", "sku": "KBD-14", "dmsCode": "780256" }, "loaded": 500, "delivered": 0, "vanSold": 500, "freeIssued": 0, "returned": 0, "expectedRemaining": 0, "variance": 0, "salesValue": { "amount": "1500000.00", "currency": "UGX" }, "varianceValue": { "amount": "0.00", "currency": "UGX" } } ], "closedForFinance": true, "closedAt": "2026-10-02T15:30:00.000Z", "updatedAt": "2026-10-02T15:30:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`, `module_disabled`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "trips:read" ], "x-mikono-idempotency": "none" } }, "/stock-adjustments": { "post": { "operationId": "createStockAdjustment", "summary": "Adjust stock at a location", "description": "Creates, approves and posts a stock adjustment through Mikono's adjustment core: stock levels, cost layers, movements and the inventory journal. Each line is a signed change in stock; taking out more than the location holds is `422 insufficient_stock`. Stock taken out leaves at the location's own valuation: `unitCost` is accepted only on lines that add stock. Needs the Inventory module. Readable afterwards on `GET /stock-levels` and `GET /stock-movements`. The document is posted at once, as Go's van sale is: API writes go through Mikono's server-side cores, which apply no amount-tiered approval. A reference inside the body that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field.", "tags": [ "Stock" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockAdjustmentCreate" }, "example": { "locationId": "j9701a2s3d4f5g6h7j8k9l0z1x2c3v4b", "reason": "damage", "notes": "Crate dropped at loading", "lines": [ { "product": { "code": "780116" }, "quantity": -3 } ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockAdjustment" }, "example": { "id": "jd7a2s5d8f1g4h7j0k3l6z9x2c5v8b1n", "adjustmentNumber": "ADJ-000031", "status": "posted", "adjustmentDate": "2026-10-02", "reason": "damage", "customReason": null, "location": { "id": "j9701a2s3d4f5g6h7j8k9l0z1x2c3v4b", "name": "Main Depot", "type": "warehouse" }, "lines": [ { "product": { "id": "k572a9b8c7d6e5f4g3h2j1k0m9n8p7q6", "name": "Bell Lager 500ml", "sku": "KBD-01", "dmsCode": "780116" }, "previousQuantity": 500, "newQuantity": 497, "quantity": -3, "unitCost": { "amount": "1900.00", "currency": "UGX" }, "totalCost": { "amount": "5700.00", "currency": "UGX" } } ], "totalValue": { "amount": "5700.00", "currency": "UGX" }, "notes": "Crate dropped at loading", "externalCodes": {}, "createdAt": "2026-10-02T12:00:00.000Z", "updatedAt": "2026-10-02T12:00:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `idempotency_key_required`, `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`, `module_disabled`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `idempotency_key_reused`, `insufficient_stock`, `location_not_found`, `period_closed`, `product_not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "stock:write" ], "x-mikono-idempotency": "required" } }, "/stock-levels": { "get": { "operationId": "listStockLevels", "summary": "List stock levels", "description": "Quantities per product and warehouse or van, without value fields. A snapshot list: levels carry no `updatedAt`, so `updatedSince` and `externalCode` are refused (`400 invalid_field`). Use `GET /stock-movements?since=` as the change feed. Sorted newest level first.", "tags": [ "Stock" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "locationId", "in": "query", "required": false, "description": "Only this warehouse or van.", "schema": { "type": "string" } }, { "name": "productId", "in": "query", "required": false, "description": "Only this product.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockLevelPage" }, "example": { "data": [ { "id": "kj73m5p7r9t1v3x5z7b9d1f3h5k7m9p1", "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "name": "Tusker Lager 500ml", "sku": "KBD-14", "dmsCode": "780256" }, "location": { "id": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "name": "Truck UBC 512K", "type": "van" }, "quantityOnHand": 450, "quantityAllocated": 0, "quantityAvailable": 450, "unit": "bottle", "batchNumber": null, "expiryDate": null, "asOf": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "stock:read" ], "x-mikono-idempotency": "none" } }, "/stock-movements": { "get": { "operationId": "listStockMovements", "summary": "List stock movements", "description": "Every recorded stock movement. With `since` (or `updatedSince`, the same thing here), oldest first from that time: the stock change feed. Without it, newest first. `unitCost` appears only when the key also holds `payments:read`. Filters apply after each page is read, so a page can be short while `hasMore` is true.", "tags": [ "Stock" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "locationId", "in": "query", "required": false, "description": "Movements of stock at this warehouse or van (a transfer writes one movement per side).", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Movements recorded at or after this time, oldest first: the stock change feed. `updatedSince` means the same here.", "schema": { "type": "string", "format": "date-time" } }, { "name": "type", "in": "query", "required": false, "description": "What moved the stock.", "schema": { "type": "string", "enum": [ "purchase", "sale", "adjustment", "transfer", "return_from_customer", "return_to_vendor", "production_in", "production_out" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockMovementPage" }, "example": { "data": [ { "id": "kk75p7r9t1v3x5z7b9d1f3h5k7m9p1r3", "transactionNumber": "TXN-004918", "date": "2026-10-02", "type": "sale", "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "name": "Tusker Lager 500ml", "sku": "KBD-14", "dmsCode": "780256" }, "location": { "id": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "name": "Truck UBC 512K", "type": "van" }, "fromLocation": { "id": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "name": "Truck UBC 512K", "type": "van" }, "toLocation": null, "quantity": -50, "unitCost": { "amount": "2350.00", "currency": "UGX" }, "reference": { "type": "invoice", "id": "j971w3y5a7c9e1g3j5l7n9q1s3u5w7y9", "number": "INV-000412" }, "reason": null, "createdAt": "2026-10-02T07:06:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "stock:read" ], "x-mikono-idempotency": "none" } }, "/stock-transfers": { "post": { "operationId": "createStockTransfer", "summary": "Transfer stock between locations", "description": "Creates, approves and completes a transfer through Mikono's transfer core, at the source location's cost. The source must hold the quantity (`422 insufficient_stock`). A van-to-van transfer follows Mikono's trip rules. Needs the Inventory module. The document is posted at once, as Go's van sale is: API writes go through Mikono's server-side cores, which apply no amount-tiered approval. A reference inside the body that does not exist, or belongs to another organisation, answers `422` with a `*_not_found` code and `errors[]` naming the field.", "tags": [ "Stock" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "Unknown fields are rejected with `400 unknown_field`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockTransferCreate" }, "example": { "fromLocationId": "j9701a2s3d4f5g6h7j8k9l0z1x2c3v4b", "toLocationId": "j97b4m2x8c1v5n3q7w6e9r0t2y4u8i1o", "reference": "Top-up load", "lines": [ { "product": { "code": "780116" }, "quantity": 4, "unit": "pack" } ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockTransfer" }, "example": { "id": "jt7q1w4e7r0t3y6u9i2o5p8a1s4d7f0g", "transferNumber": "TRF-000088", "status": "completed", "transferDate": "2026-10-02", "from": { "id": "j9701a2s3d4f5g6h7j8k9l0z1x2c3v4b", "name": "Main Depot", "type": "warehouse" }, "to": { "id": "j97b4m2x8c1v5n3q7w6e9r0t2y4u8i1o", "name": "Van UBL 123X", "type": "van" }, "reference": "Top-up load", "lines": [ { "product": { "id": "k572a9b8c7d6e5f4g3h2j1k0m9n8p7q6", "name": "Bell Lager 500ml", "sku": "KBD-01", "dmsCode": "780116" }, "quantity": 100, "unitCost": { "amount": "1900.00", "currency": "UGX" }, "totalCost": { "amount": "190000.00", "currency": "UGX" } } ], "totalValue": { "amount": "190000.00", "currency": "UGX" }, "notes": null, "externalCodes": {}, "createdAt": "2026-10-02T06:30:00.000Z", "updatedAt": "2026-10-02T06:30:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `idempotency_key_required`, `invalid_field`, `invalid_json`, `key_in_query`, `required_field`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`, `module_disabled`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict. Codes: `idempotency_in_progress`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Content. Codes: `business_rule`, `idempotency_key_reused`, `insufficient_stock`, `location_not_found`, `period_closed`, `product_not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "write", "x-mikono-scopes": [ "stock:write" ], "x-mikono-idempotency": "required" } }, "/trips": { "get": { "operationId": "listTrips", "summary": "List trips", "description": "Trips, newest trip date first; with `updatedSince`, by `updatedAt` ascending. An unknown `routeCode` returns an empty page.", "tags": [ "Trips" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "date", "in": "query", "required": false, "description": "Trips planned for this business date.", "schema": { "type": "string", "format": "date" } }, { "name": "routeCode", "in": "query", "required": false, "description": "Trips on the route with this DMS code.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "`reconciling`: back at the depot, settlement open. `closed`: settled.", "schema": { "type": "string", "enum": [ "planning", "loading", "in_transit", "reconciling", "closed", "cancelled" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripPage" }, "example": { "data": [ { "id": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "date": "2026-10-02", "status": "in_transit", "route": { "id": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "name": "KBDVSM001 · Ntinda – Naguru", "code": "KBDVSM001" }, "truck": { "id": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "name": "Truck UBC 512K", "vehicleRegistration": "UBC 512K" }, "warehouseId": "kh74c6e8g0j2l4n6q8s0u2w4y6a8c0e2", "crew": [ { "userId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "name": "Brian Okello", "role": "salesperson" }, { "userId": "jn7e6g8j0l2n4q6s8u0w2y4a6c8e0g2j", "name": "Peter Ssali", "role": "driver" } ], "startTime": "2026-10-02T04:00:00.000Z", "endTime": null, "cancelledAt": null, "closedForFinanceAt": null, "createdAt": "2026-10-01T15:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "trips:read" ], "x-mikono-idempotency": "none" } }, "/trips/{id}": { "get": { "operationId": "getTrip", "summary": "Get a trip", "description": "The trip with its crew, stop counts, Goods Issued Notes with their lines, and stock returns.", "tags": [ "Trips" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trip" }, "example": { "id": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "date": "2026-10-02", "status": "in_transit", "route": { "id": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "name": "KBDVSM001 · Ntinda – Naguru", "code": "KBDVSM001" }, "truck": { "id": "kh75d7f9h1k3m5p7r9t1v3x5z7b9d1f3", "name": "Truck UBC 512K", "vehicleRegistration": "UBC 512K" }, "warehouseId": "kh74c6e8g0j2l4n6q8s0u2w4y6a8c0e2", "crew": [ { "userId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "name": "Brian Okello", "role": "salesperson" }, { "userId": "jn7e6g8j0l2n4q6s8u0w2y4a6c8e0g2j", "name": "Peter Ssali", "role": "driver" } ], "startTime": "2026-10-02T04:00:00.000Z", "endTime": null, "cancelledAt": null, "closedForFinanceAt": null, "createdAt": "2026-10-01T15:00:00.000Z", "updatedAt": "2026-10-02T07:15:00.000Z", "stops": { "planned": 15, "done": 6, "missed": 1, "pending": 8 }, "loads": [ { "id": "ks73h5k7m9p1r3t5v7x9z1b3d5f7h9k1", "noteNumber": "GIN-KBDVSM001-20261002", "direction": "out", "status": "attested", "issuedAt": "2026-10-02T03:40:00.000Z", "attestedAt": "2026-10-02T03:55:00.000Z", "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "name": "Tusker Lager 500ml", "sku": "KBD-14", "dmsCode": "780256" }, "issuedQty": 500, "attestedQty": 500 }, { "product": { "id": "kd72r4t6v8x0z2b4d6f8h0k2m4p6r8t0", "name": "Bell Lager 500ml", "sku": "KBD-01", "dmsCode": "780116" }, "issuedQty": 250, "attestedQty": 250 } ] } ], "returns": [ { "id": "ks74j6l8n0q2s4u6w8y0a2c4e6g8j0l2", "status": "pending", "requestedAt": "2026-10-02T07:12:00.000Z", "reviewedAt": null, "lines": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "name": "Tusker Lager 500ml", "sku": "KBD-14", "dmsCode": "780256" }, "returnedQty": 2, "acceptedQty": null, "damagedQty": null } ] } ] } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "trips:read" ], "x-mikono-idempotency": "none" } }, "/trips/{id}/locations": { "get": { "operationId": "listTripLocations", "summary": "List a trip's GPS pings", "description": "Pings from the crew's phones, oldest first. `gps` appears only when the key also holds `customers:pii`.", "tags": [ "Field activity" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "since", "in": "query", "required": false, "description": "Pings at or after this time, oldest first.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripLocationPage" }, "example": { "data": [ { "timestamp": "2026-10-02T07:15:00.000Z", "userId": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "gps": { "latitude": 0.350849, "longitude": 32.612542 }, "accuracyMeters": 8, "speedKph": 0, "headingDegrees": null, "source": "go" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "trips:read" ], "x-mikono-idempotency": "none" } }, "/trips/{id}/settlement": { "get": { "operationId": "getTripSettlement", "summary": "Get a trip's settlement", "description": "The figures of the depot settlement screen for this trip, computed by the same code. Before the trip is closed they are provisional; `cashCounted` and `variance` are null until the depot counts the cash. `403 module_disabled` when the organisation has turned off the Delivery module, as the screen does.", "tags": [ "Trips" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Mikono id of the record." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripSettlement" }, "example": { "tripId": "kt71f3h5k7m9p1r3t5v7x9z1b3d5f7h9", "date": "2026-10-02", "status": "closed", "routeName": "KBDVSM001 · Ntinda – Naguru", "salesValue": { "amount": "3150000.00", "currency": "UGX" }, "discount": { "amount": "0.00", "currency": "UGX" }, "creditSales": { "amount": "0.00", "currency": "UGX" }, "nonCashCollections": { "amount": "420000.00", "currency": "UGX" }, "prepayments": { "amount": "0.00", "currency": "UGX" }, "debtCollectionsCash": { "amount": "0.00", "currency": "UGX" }, "creditNotes": { "amount": "6000.00", "currency": "UGX" }, "cashRefunds": { "amount": "0.00", "currency": "UGX" }, "cashExpenses": { "amount": "0.00", "currency": "UGX" }, "cashExpectedFromSales": { "amount": "2724000.00", "currency": "UGX" }, "floatIssued": { "amount": "50000.00", "currency": "UGX" }, "cashExpected": { "amount": "2774000.00", "currency": "UGX" }, "cashCounted": { "amount": "2774000.00", "currency": "UGX" }, "variance": { "amount": "0.00", "currency": "UGX" }, "varianceReason": null, "mobileMoney": { "amount": "420000.00", "currency": "UGX" }, "credit": { "amount": "0.00", "currency": "UGX" }, "collected": { "amount": "3194000.00", "currency": "UGX" }, "stockVarianceValue": { "amount": "0.00", "currency": "UGX" }, "stockReconciliation": [ { "product": { "id": "kd71q3s5u7w9y1a3c5e7g9j1l3n5q7s9", "name": "Tusker Lager 500ml", "sku": "KBD-14", "dmsCode": "780256" }, "loaded": 500, "delivered": 0, "vanSold": 500, "freeIssued": 0, "returned": 0, "expectedRemaining": 0, "variance": 0, "salesValue": { "amount": "1500000.00", "currency": "UGX" }, "varianceValue": { "amount": "0.00", "currency": "UGX" } } ], "closedForFinance": true, "closedAt": "2026-10-02T15:30:00.000Z", "updatedAt": "2026-10-02T15:30:00.000Z" } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`, `module_disabled`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "trips:read" ], "x-mikono-idempotency": "none" } }, "/visits": { "get": { "operationId": "listVisits", "summary": "List planned and missed visits", "description": "The day's planned outlet visits with what happened: `visited`, `skipped_with_reason`, `not_visited` (missed) or `open` (today or later, not visited yet). `date` is required; `updatedSince` is refused.", "tags": [ "Field activity" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/ExternalCode" }, { "name": "date", "in": "query", "required": false, "description": "Required. The business date of the plan.", "schema": { "type": "string", "format": "date" } }, { "name": "salespersonId", "in": "query", "required": false, "description": "Only this salesperson's visits.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitPage" }, "example": { "data": [ { "id": "kw79t1v3x5z7b9d1f3h5k7m9p1r3t5v7", "date": "2026-10-02", "salesperson": { "id": "jn7d5f7h9k1m3p5r7t9v1x3z5b7d9f1h", "name": "Brian Okello" }, "customerId": "jx7a1c3e5g7j9l1n3q5s7u9w1y3a5c7e", "customerName": "Hilltop Sports Bar, Ntinda", "routeId": "m173k5m7p9r1t3v5x7z9b1d3f5h7k9m1", "planned": true, "state": "visited", "reason": null, "status": "completed", "checkInTime": "2026-10-02T07:02:00.000Z", "checkOutTime": "2026-10-02T07:14:00.000Z", "outcome": "sale", "updatedAt": "2026-10-02T07:15:00.000Z" } ], "nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwNzoxNTowMC4wMDBaIiwiaWQiOiJqeDdhIn0", "hasMore": true } } } }, "400": { "description": "Bad Request. Codes: `invalid_field`, `key_in_query`, `unknown_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized. Codes: `unauthorized`, `wrong_environment`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden. Codes: `api_disabled`, `insufficient_scope`, `ip_not_allowed`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests. Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error. Codes: `server_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-mikono-kind": "read", "x-mikono-scopes": [ "trips:read" ], "x-mikono-idempotency": "none" } } }, "webhooks": { "credit_note.created": { "post": { "operationId": "webhook_credit_note_created", "summary": "A credit note was created", "description": "`data.object` is `GET /credit-notes/{id}`. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteCreatedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "customer.created": { "post": { "operationId": "webhook_customer_created", "summary": "A customer (outlet) was created", "description": "`data.object` is `GET /customers/{id}`. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreatedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "customer.updated": { "post": { "operationId": "webhook_customer_updated", "summary": "A customer changed, was archived, deleted or restored", "description": "`data.object` is `GET /customers/{id}`, or a `DeletedRecord` once the customer is deleted. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "invoice.created": { "post": { "operationId": "webhook_invoice_created", "summary": "An invoice was created", "description": "`data.object` is `GET /invoices/{id}`. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceCreatedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "invoice.updated": { "post": { "operationId": "webhook_invoice_updated", "summary": "An invoice changed (payment or credit applied, issued, edited)", "description": "`data.object` is `GET /invoices/{id}`; `balanceDue` and `status` show the effect. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "invoice.voided": { "post": { "operationId": "webhook_invoice_voided", "summary": "An invoice was voided", "description": "`data.object` is `GET /invoices/{id}`. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceVoidedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "order.created": { "post": { "operationId": "webhook_order_created", "summary": "A sales order was created", "description": "`data.object` is `GET /orders/{id}`. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreatedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "order.status_changed": { "post": { "operationId": "webhook_order_status_changed", "summary": "A sales order's status changed", "description": "`data.object` is `GET /orders/{id}` with the new status. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusChangedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "payment.created": { "post": { "operationId": "webhook_payment_created", "summary": "A customer payment was recorded", "description": "`data.object` is `GET /payments/{id}`. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCreatedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "payment.reversed": { "post": { "operationId": "webhook_payment_reversed", "summary": "A customer payment was voided", "description": "`data.object` is `GET /payments/{id}`. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReversedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "product.created": { "post": { "operationId": "webhook_product_created", "summary": "A product was created", "description": "`data.object` is `GET /products/{id}`. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreatedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "product.updated": { "post": { "operationId": "webhook_product_updated", "summary": "A product changed or was archived or deleted", "description": "`data.object` is `GET /products/{id}`, or a `DeletedRecord` once the product is deleted. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "settlement.closed": { "post": { "operationId": "webhook_settlement_closed", "summary": "A trip's settlement was closed", "description": "`data.object` is `GET /trips/{id}/settlement`. Sent with `trip.closed`. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementClosedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "stock.movement.created": { "post": { "operationId": "webhook_stock_movement_created", "summary": "An inventory document moved stock", "description": "One event per document (an invoice, transfer, adjustment …), not per line. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockMovementCreatedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } }, "trip.closed": { "post": { "operationId": "webhook_trip_closed", "summary": "A delivery trip was closed", "description": "`data.object` is `GET /trips/{id}`. `data.object` is read when the event is sent, usually within seconds of the change, so it can already include a later change; a record deleted by then arrives as a `DeletedRecord`, and one too large to send whole as a `TruncatedRecord` naming its GET endpoint. Delivery order is not guaranteed: compare `data.object.updatedAt` with what you hold. `data.object` never carries `customers:pii` fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripClosedEvent" } } } }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } } } } }, "components": { "schemas": { "CanonicalDocumentInput": { "anyOf": [ { "type": "object", "properties": { "documentType": { "type": "string", "const": "customer" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "name": { "type": "string" }, "channel": { "type": "string" }, "phone": { "type": "string" }, "contactName": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "tin": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "priceGroup": { "type": "string" }, "routeCode": { "type": "string" }, "active": { "type": "boolean" }, "shortName": { "type": "string" }, "customerType": { "type": "string", "enum": [ "cash", "credit" ] }, "subchannel": { "type": "string" }, "segment": { "type": "string" }, "subSegments": { "type": "array", "items": { "type": "string" } }, "volumeGrade": { "type": "string" }, "territory": { "type": "string" }, "routeName": { "type": "string" }, "creditLimit": { "type": "number" }, "creditTerms": { "type": "string" }, "openAccountDate": { "type": "string" }, "outstandingBalance": { "type": "number" }, "dmsAttributes": { "type": "object", "properties": { "archiType": { "type": "string" }, "obos": { "type": "string" }, "division": { "type": "string" }, "area": { "type": "string" }, "approvalStatus": { "type": "string" }, "mpaType": { "type": "string" } }, "additionalProperties": false } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "product" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "name": { "type": "string" }, "unit": { "type": "string" }, "packSize": { "type": "number" }, "category": { "type": "string" }, "brand": { "type": "string" }, "isEmpties": { "type": "boolean" }, "barcode": { "type": "string" }, "taxCode": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "price" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "productCode": { "type": "string" }, "priceGroup": { "type": "string" }, "unit": { "type": "string" }, "unitPrice": { "type": "number" }, "effectiveFrom": { "type": "string" }, "effectiveTo": { "type": "string" } }, "required": [ "productCode", "unit", "unitPrice" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "salesman" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "name": { "type": "string" }, "routeCode": { "type": "string" }, "phone": { "type": "string" }, "locationCode": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "route_plan" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "salesmanName": { "type": "string" }, "sheet": { "type": "string" }, "visitType": { "type": "string" }, "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "enum": [ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ] }, "outlets": { "type": "array", "items": { "type": "object", "properties": { "outletCode": { "type": "string" }, "frequency": { "type": "string" }, "sequence": { "type": "number" } }, "required": [ "outletCode", "frequency", "sequence" ], "additionalProperties": false } } }, "required": [ "day", "outlets" ], "additionalProperties": false } } }, "required": [ "days" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "location" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "name": { "type": "string" }, "locationType": { "type": "string", "enum": [ "warehouse", "van", "damages" ] }, "routeCode": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "name", "locationType" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "reason" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "description": { "type": "string" }, "category": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "description" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "van_issue" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "fromLocationCode": { "type": "string" }, "toLocationCode": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productCode": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "reasonCode": { "type": "string" } }, "required": [ "productCode", "quantity", "unit" ], "additionalProperties": false } } }, "required": [ "fromLocationCode", "toLocationCode", "lines" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "van_unload" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "fromLocationCode": { "type": "string" }, "toLocationCode": { "type": "string" }, "reasonCode": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productCode": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "reasonCode": { "type": "string" } }, "required": [ "productCode", "quantity", "unit" ], "additionalProperties": false } } }, "required": [ "fromLocationCode", "toLocationCode", "lines" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "sale_invoice" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "paymentTerms": { "type": "string", "enum": [ "cash", "credit" ] }, "paymentMethod": { "type": "string" }, "locationCode": { "type": "string" }, "orderNumber": { "type": "string" }, "subtotal": { "type": "number" }, "discountTotal": { "type": "number" }, "taxTotal": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productCode": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "unitPrice": { "type": "number" }, "discount": { "type": "number" }, "tax": { "type": "number" }, "lineType": { "type": "string", "enum": [ "selling", "free_issue", "empties" ] }, "lineTotal": { "type": "number" }, "reasonCode": { "type": "string" } }, "required": [ "productCode", "quantity", "unit", "unitPrice", "lineType" ], "additionalProperties": false } } }, "required": [ "paymentTerms", "lines" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "sale_return" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "invoiceNumber": { "type": "string" }, "locationCode": { "type": "string" }, "reasonCode": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productCode": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "unitPrice": { "type": "number" }, "discount": { "type": "number" }, "tax": { "type": "number" }, "lineType": { "type": "string", "enum": [ "selling", "free_issue", "empties" ] }, "lineTotal": { "type": "number" }, "reasonCode": { "type": "string" } }, "required": [ "productCode", "quantity", "unit", "unitPrice", "lineType" ], "additionalProperties": false } } }, "required": [ "lines" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "credit_note" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "invoiceNumber": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "amount": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productCode": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "unitPrice": { "type": "number" }, "discount": { "type": "number" }, "tax": { "type": "number" }, "lineType": { "type": "string", "enum": [ "selling", "free_issue", "empties" ] }, "lineTotal": { "type": "number" }, "reasonCode": { "type": "string" } }, "required": [ "productCode", "quantity", "unit", "unitPrice", "lineType" ], "additionalProperties": false } } }, "required": [ "amount" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "collection" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "paymentMethod": { "type": "string" }, "amount": { "type": "number" }, "reference": { "type": "string" }, "chequeNumber": { "type": "string" }, "chequeDate": { "type": "string" }, "bankName": { "type": "string" }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "invoiceNumber": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "invoiceNumber", "amount" ], "additionalProperties": false } } }, "required": [ "paymentMethod", "amount", "allocations" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "cheque_status" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "chequeNumber": { "type": "string" }, "collectionNumber": { "type": "string" }, "amount": { "type": "number" }, "bankName": { "type": "string" }, "reasonCode": { "type": "string" } }, "required": [ "chequeNumber" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "stock_adjustment" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "locationCode": { "type": "string" }, "reasonCode": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productCode": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "reasonCode": { "type": "string" } }, "required": [ "productCode", "quantity", "unit" ], "additionalProperties": false } } }, "required": [ "locationCode", "lines" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "supplier_invoice" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "supplierCode": { "type": "string" }, "supplierReference": { "type": "string" }, "locationCode": { "type": "string" }, "dueDate": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productCode": { "type": "string" }, "quantity": { "type": "number" }, "receivedQuantity": { "type": "number" }, "unit": { "type": "string" }, "unitPrice": { "type": "number" }, "tax": { "type": "number" } }, "required": [ "productCode", "quantity", "unit", "unitPrice" ], "additionalProperties": false } } }, "required": [ "locationCode", "lines" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "stock_snapshot" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "locationCode": { "type": "string" }, "asOf": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productCode": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "reasonCode": { "type": "string" } }, "required": [ "productCode", "quantity", "unit" ], "additionalProperties": false } } }, "required": [ "locationCode", "lines" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "route_settlement" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "cashHandedIn": { "type": "number" }, "chequeAmount": { "type": "number" }, "mobileMoneyAmount": { "type": "number" }, "creditSales": { "type": "number" }, "closingStock": { "type": "array", "items": { "type": "object", "properties": { "productCode": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "reasonCode": { "type": "string" } }, "required": [ "productCode", "quantity", "unit" ], "additionalProperties": false } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "documentType": { "type": "string" }, "documentNumber": { "type": "string" }, "value": { "type": "number" } }, "required": [ "documentType", "documentNumber" ], "additionalProperties": false } }, "totals": { "type": "array", "items": { "type": "object", "properties": { "documentType": { "type": "string" }, "count": { "type": "number" }, "value": { "type": "number" } }, "required": [ "documentType", "count" ], "additionalProperties": false } } }, "required": [ "cashHandedIn" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "const": "daily_totals" }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": { "type": "object", "properties": { "totals": { "type": "array", "items": { "type": "object", "properties": { "documentType": { "type": "string" }, "count": { "type": "number" }, "value": { "type": "number" } }, "required": [ "documentType", "count" ], "additionalProperties": false } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "documentType": { "type": "string" }, "documentNumber": { "type": "string" }, "value": { "type": "number" } }, "required": [ "documentType", "documentNumber" ], "additionalProperties": false } } }, "required": [ "totals" ], "additionalProperties": false } }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "documentType": { "type": "string", "enum": [ "distributor", "van_stock_request", "van_count", "van_damage", "debit_note", "order", "transfer", "stock_take", "supplier_return", "fiscal_status", "promotion" ] }, "documentNumber": { "type": "string" }, "distributorCode": { "type": "string" }, "documentDate": { "type": "string" }, "dmsStatus": { "type": "string" }, "salesmanCode": { "type": "string" }, "customerCode": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "number" }, "sentAt": { "type": "string" }, "body": {} }, "required": [ "documentType", "documentNumber", "distributorCode", "documentDate", "dmsStatus" ], "additionalProperties": false } ], "description": "One DMS document in Mikono's canonical form: a common header plus a `body` whose shape depends on `documentType`. For master data (customer, product, salesman, location, reason) `documentNumber` is the record's DMS code. `dmsStatus` is the DMS's own status; a changed status on a known document is an update (the old version becomes `superseded`). Unknown fields are rejected here. Partner formats such as EDGE 365 are planned to go through their own adapter; none is mapped yet." }, "CanonicalDocumentType": { "type": "string", "enum": [ "customer", "product", "price", "salesman", "route_plan", "location", "reason", "distributor", "van_stock_request", "van_issue", "van_unload", "van_count", "van_damage", "sale_invoice", "sale_return", "credit_note", "debit_note", "order", "collection", "cheque_status", "route_settlement", "supplier_invoice", "stock_adjustment", "transfer", "stock_take", "supplier_return", "stock_snapshot", "daily_totals", "fiscal_status", "promotion" ] }, "CompetitorObservation": { "type": "object", "properties": { "id": { "type": "string" }, "siteKind": { "type": "string", "description": "`distributor` (a depot) or `retailer` (an outlet)." }, "customerId": { "type": "string", "description": "The site's customer record." }, "brand": { "type": "string" }, "isOwnBrand": { "type": "boolean" }, "quantity": { "type": "number" }, "observedAt": { "type": "string", "format": "date", "examples": [ "2026-10-02" ] }, "observedBy": { "type": "string" }, "visitId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "photoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Present only when the key holds `customers:pii`. The URL expires." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "siteKind", "customerId", "brand", "isOwnBrand", "quantity", "observedAt", "observedBy", "visitId", "createdAt", "updatedAt" ], "description": "A count of one brand's stock seen at a site." }, "CompetitorObservationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitorObservation" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "CreditNote": { "type": "object", "properties": { "id": { "type": "string" }, "creditNoteNumber": { "type": "string" }, "status": { "type": "string", "description": "`draft`, `issued`, `partially_applied`, `applied`, `refunded` or `voided`." }, "type": { "type": "string", "description": "`return` (goods back), `adjustment`, `discount`, `correction` or `other`." }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/DocumentCustomer" }, { "type": "null" } ] }, "invoiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "returnId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The return whose restock raised this note." }, "tripId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The delivery trip the return was taken on." }, "issueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteLine" } }, "linesTruncated": { "type": "boolean", "description": "true when this document has more than 500 lines and applications together: only the first 500 are returned. A list page also stops early (`hasMore` true) rather than read more than about 2,500 child rows in all." }, "subtotal": { "$ref": "#/components/schemas/Money" }, "discount": { "$ref": "#/components/schemas/Money" }, "tax": { "$ref": "#/components/schemas/Money" }, "total": { "$ref": "#/components/schemas/Money" }, "remainingAmount": { "$ref": "#/components/schemas/Money" }, "cashRefundAmount": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Cash handed back at a delivery stop." }, "currency": { "type": "string" }, "applications": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteApplication" } }, "fiscal": { "$ref": "#/components/schemas/Fiscal" }, "posting": { "$ref": "#/components/schemas/Posting" }, "externalCodes": { "$ref": "#/components/schemas/ExternalCodes", "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "creditNoteNumber", "status", "type", "customer", "invoiceId", "returnId", "tripId", "issueDate", "reason", "notes", "lines", "linesTruncated", "subtotal", "discount", "tax", "total", "remainingAmount", "cashRefundAmount", "currency", "applications", "fiscal", "posting", "externalCodes", "createdAt", "updatedAt" ], "description": "`remainingAmount` is the credit not yet applied to invoices or refunded." }, "CreditNoteApplication": { "type": "object", "properties": { "invoiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The invoice the credit was applied to; null for a refund." }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "$ref": "#/components/schemas/Money" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date" }, "refundPaymentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The refund payment, when the credit was paid out." } }, "required": [ "invoiceId", "invoiceNumber", "amount", "date", "refundPaymentId" ] }, "CreditNoteCancel": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why the credit note was cancelled; kept on the audit trail." } }, "additionalProperties": false, "description": "Send `{}` when there is no reason to record." }, "CreditNoteCreate": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/RecordRefInput" }, "invoiceId": { "type": "string", "description": "The invoice credited. Its open balance takes the credit first; the rest stays on the customer's account." }, "type": { "type": "string", "enum": [ "adjustment", "discount", "correction", "other" ], "description": "Default `adjustment`. Goods coming back are a return: `POST /returns`." }, "issueDate": { "type": "string", "format": "date", "description": "Defaults to today in the organisation's time zone." }, "reason": { "type": "string" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteCreateLineInput" }, "description": "1 to 100 lines." } }, "required": [ "customer", "lines" ], "additionalProperties": false, "description": "A credit note to issue and post: DR revenue and VAT, CR receivables." }, "CreditNoteCreateLineInput": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/RecordRefInput" }, "description": { "type": "string", "description": "Required when no product is named (omit `product` for a credit that names none)." }, "quantity": { "type": "number", "description": "In `unit`; more than zero." }, "unit": { "type": "string", "enum": [ "base", "pack" ], "description": "`base` (default): the product's stock unit; `pack`: its pack (case). A pack quantity is converted to stock units with the product's pack size, and a pack price is divided by it." }, "unitPrice": { "$ref": "#/components/schemas/MoneyInput" }, "taxRate": { "type": "number", "description": "VAT rate in percent. Defaults to the product's tax rate, or 0 on a line with no product or when the organisation does not charge sales tax." } }, "required": [ "quantity", "unitPrice" ], "additionalProperties": false, "description": "`unitPrice` is the credit per `unit` before tax, in the organisation's base currency. Omit `product` for a credit that names none." }, "CreditNoteCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "credit_note.created" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/CreditNote" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "CreditNoteLine": { "type": "object", "properties": { "product": { "anyOf": [ { "$ref": "#/components/schemas/DocumentProduct" }, { "type": "null" } ], "description": "null on lines that name no product." }, "description": { "type": "string" }, "type": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "$ref": "#/components/schemas/Money" }, "discount": { "$ref": "#/components/schemas/Money" }, "taxRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "tax": { "$ref": "#/components/schemas/Money" }, "amount": { "$ref": "#/components/schemas/Money" } }, "required": [ "product", "description", "type", "quantity", "unitPrice", "discount", "taxRate", "tax", "amount" ] }, "CreditNotePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNote" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "Customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "shortName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "description": "`active`, `inactive`, `pending` or `archived`.", "examples": [ "active" ] }, "type": { "type": [ "string", "null" ], "enum": [ "cash", "credit", null ], "description": "Cash customer or credit account." }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subChannel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "segment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subSegments": { "type": "array", "items": { "type": "string" } }, "volumeGrade": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "territory": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "routes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code" ] }, "description": "Routes (beats) this outlet is an active stop on, with each route's code." }, "priceGroup": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Price group (tier) the outlet buys at: its own override, else its customer group's default tier." }, "creditLimit": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Base selling price, VAT-exclusive." }, "creditTerms": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "creditStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "balance": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Base selling price, VAT-exclusive." }, "location": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/CustomerAddress" }, "gps": { "anyOf": [ { "$ref": "#/components/schemas/Gps" }, { "type": "null" } ], "description": "Only with the `customers:pii` scope." } }, "required": [ "address" ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIN. Only with the `customers:pii` scope." }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerContact" }, "description": "Contact people and phones. Only with the `customers:pii` scope." }, "externalCodes": { "$ref": "#/components/schemas/ExternalCodes", "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "name", "shortName", "status", "type", "channel", "subChannel", "segment", "subSegments", "volumeGrade", "territory", "routes", "priceGroup", "creditLimit", "creditTerms", "creditStatus", "balance", "location", "externalCodes", "createdAt", "updatedAt" ], "description": "An outlet or account. PII fields appear only for keys with `customers:pii`." }, "CustomerAddress": { "type": "object", "properties": { "street": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "street", "city", "region", "postalCode", "country" ] }, "CustomerContact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isPrimary": { "type": "boolean" } }, "required": [ "name", "phone", "email", "title", "isPrimary" ] }, "CustomerCreate": { "type": "object", "properties": { "name": { "type": "string" }, "shortName": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "type": { "type": "string", "enum": [ "cash", "credit" ] }, "channel": { "type": "string", "description": "A trade channel configured for the organisation (Settings → Categories)." }, "subChannel": { "type": "string" }, "subSegments": { "type": "array", "items": { "type": "string" } }, "territory": { "type": "string" }, "creditLimit": { "anyOf": [ { "$ref": "#/components/schemas/MoneyInput" }, { "type": "null" } ], "description": "null clears the limit. Currency must be the organisation's base currency." }, "creditTerms": { "type": "string" }, "taxId": { "type": "string" }, "location": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } }, "additionalProperties": false }, "gps": { "$ref": "#/components/schemas/GpsInput" } }, "additionalProperties": false }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" } }, "additionalProperties": false }, "externalCodes": { "type": "object", "properties": { "dms": { "type": "string" } }, "additionalProperties": false, "description": "The outlet's DMS code (`UG` + 7 digits). A code another outlet already carries is `409 code_conflict`.", "examples": [ { "dms": "UG2000123" } ] } }, "required": [ "name" ], "additionalProperties": false, "description": "A new outlet. `taxId`, `location.gps` and `contact` need the `customers:pii` scope as well as `customers:write`." }, "CustomerCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "customer.created" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Customer" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "CustomerPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/Customer" }, { "$ref": "#/components/schemas/Tombstone" } ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "CustomerRefInput": { "type": "object", "properties": { "id": { "type": "string", "description": "Mikono id of the customer (outlet)." }, "code": { "type": "string", "description": "DMS code of the customer (outlet).", "examples": [ "UG2000123" ] } }, "additionalProperties": false, "description": "The customer (outlet), by Mikono `id` or DMS `code`: send exactly one." }, "CustomerUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "customer.updated" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Customer" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "CustomerUpsert": { "type": "object", "properties": { "name": { "type": "string", "description": "Required when the code is new." }, "shortName": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "type": { "type": "string", "enum": [ "cash", "credit" ] }, "channel": { "type": "string", "description": "A trade channel configured for the organisation (Settings → Categories)." }, "subChannel": { "type": "string" }, "subSegments": { "type": "array", "items": { "type": "string" } }, "territory": { "type": "string" }, "creditLimit": { "anyOf": [ { "$ref": "#/components/schemas/MoneyInput" }, { "type": "null" } ], "description": "null clears the limit. Currency must be the organisation's base currency." }, "creditTerms": { "type": "string" }, "taxId": { "type": "string" }, "location": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } }, "additionalProperties": false }, "gps": { "$ref": "#/components/schemas/GpsInput" } }, "additionalProperties": false }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Fields to set. Omitted fields keep their value on an existing outlet." }, "DayOfWeek": { "type": "string", "enum": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ] }, "DayOfWeekInput": { "type": "string", "enum": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ] }, "DeletedRecord": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the record was deleted (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC)." } }, "required": [ "id", "deleted", "deletedAt", "updatedAt" ], "description": "A record deleted by the time its event was sent (for customers and products, also the `*.updated` event of the deletion)." }, "DmsDocuments": { "anyOf": [ { "$ref": "#/components/schemas/CanonicalDocumentInput" }, { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalDocumentInput" }, "description": "1 to 500 documents (50 in sync mode).", "minItems": 1, "maxItems": 500 } }, "required": [ "documents" ], "additionalProperties": false } ], "description": "One canonical document, or `{ documents: [...] }`." }, "DmsFileAccepted": { "type": "object", "properties": { "batchId": { "type": "string", "description": "The file's batch. Read its flags at `/dms/{system}/files/{batchId}/flags`." }, "status": { "type": "string", "enum": [ "received", "parsed", "partially_rejected", "rejected" ], "description": "`received` until the file has been read; then `parsed` (every document received), `partially_rejected` or `rejected` (the whole file, or every document in it)." }, "duplicate": { "type": "boolean", "description": "True when this exact file (same SHA-256) was received before and not rejected: the existing batch is returned and nothing is processed again. A rejected file can be sent again." }, "fileName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "From the multipart part's filename or the `X-File-Name` header; null when neither was sent." }, "receivedAt": { "type": "string", "format": "date-time", "description": "When the batch was first received." } }, "required": [ "batchId", "status", "duplicate", "fileName", "receivedAt" ] }, "DmsFlagFile": { "type": "string", "description": "The batch's flag file: `` with one `` per document (`documentType`, `documentNumber`, `distributorCode`, `state` = received | posted | rejected | superseded, `reasonCode` R01–R09 and the reason as text when rejected, `postedAt`, `mikonoRef`, `quickbooksRef` when posted). A document that could not be read is a rejected flag with its `position` in the file. A file that could not be read at all has one flag with `level=\"file\"` and the reason." }, "DmsFlagPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Flag" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "DmsIngestResult": { "type": "object", "properties": { "batchId": { "type": "string", "description": "The stored batch. A resend of the same body returns the same batch." }, "batchStatus": { "type": "string", "enum": [ "received", "parsed", "partially_rejected", "rejected" ] }, "mode": { "type": "string", "enum": [ "async", "sync" ] }, "duplicate": { "type": "boolean", "description": "True when this exact body was received before; the flags are the documents' current ones." }, "flags": { "type": "array", "items": { "$ref": "#/components/schemas/Flag" }, "description": "One flag per document, in request order." } }, "required": [ "batchId", "batchStatus", "mode", "duplicate", "flags" ] }, "DocumentCustomer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The outlet's DMS code." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only with the `customers:pii` scope." }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIN. Only with the `customers:pii` scope." } }, "required": [ "id", "name", "code" ], "description": "The customer (outlet) a document belongs to. Full record: `GET /customers/{id}`." }, "DocumentProduct": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product's DMS SKU code." }, "name": { "type": "string" } }, "required": [ "id", "code", "name" ] }, "EmptiesMovement": { "type": "object", "properties": { "id": { "type": "string" }, "container": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dmsCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product's DMS SKU code, when it has one." } }, "required": [ "id", "name", "sku", "dmsCode" ] }, "type": { "type": "string", "enum": [ "loaded_out", "collected_at_stop", "issued_to_customer", "returned_to_depot", "sold", "adjustment", "received_from_supplier", "returned_to_supplier", "bought_back" ], "description": "What happened to the empties. `received_from_supplier` / `returned_to_supplier` are the supplier's empties (no customer or trip); `bought_back` is empties an outlet had paid for and handed back (never part of what it owes)." }, "quantity": { "type": "number" }, "customerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tripId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stopId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "container", "type", "quantity", "customerId", "tripId", "stopId", "notes", "createdAt", "updatedAt" ], "description": "A movement of returnable containers (crates, kegs) on a trip or with a customer." }, "EmptiesMovementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmptiesMovement" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "ExternalCodes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only.", "examples": [ { "dms": "UG2000123" } ] }, "Fiscal": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "EFRIS status: invoices `pending`, `sending`, `review_needed`, `fiscalised`; credit notes `pending`, `submitted`, `approved`, `rejected`, `review_needed`. null when not fiscalised." }, "fdn": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Fiscal document number from URA." }, "verificationCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URA anti-fake (verification) code." }, "qrCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The QR code text URA returned." }, "fiscalisedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When URA accepted the document (ISO 8601)." } }, "required": [ "status", "fdn", "verificationCode", "qrCode", "fiscalisedAt" ], "description": "EFRIS fiscalisation. Every field is null when the document was not fiscalised (sandbox organisations, non-VAT sales)." }, "Flag": { "type": "object", "properties": { "documentId": { "type": "string", "description": "Mikono's id for this version of the document." }, "distributorCode": { "type": "string" }, "documentType": { "$ref": "#/components/schemas/CanonicalDocumentType" }, "documentNumber": { "type": "string" }, "state": { "$ref": "#/components/schemas/FlagState" }, "reasonCode": { "$ref": "#/components/schemas/ReasonCode" }, "reasonText": { "type": "string", "description": "On `rejected`: the specific reason, e.g. `Customer UG0001234 is not known yet`." }, "note": { "type": "string", "description": "On `received`: why it has not posted yet, e.g. `Waiting for QuickBooks`." }, "mikonoRef": { "anyOf": [ { "type": "object", "properties": { "table": { "type": "string" }, "id": { "type": "string" } }, "required": [ "table", "id" ] }, { "type": "null" } ], "description": "On `posted`: the Mikono record the document created or changed." }, "quickbooksRef": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "On `posted`: the QuickBooks reference, or null when the document has no QuickBooks effect." }, "receivedAt": { "type": "string", "format": "date-time" }, "postedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the flag last changed; the pull feed is ordered by it." } }, "required": [ "documentId", "distributorCode", "documentType", "documentNumber", "state", "receivedAt", "updatedAt" ], "description": "The update flag for one DMS document. The same shape is returned by `POST /dms/{system}/documents`, `GET /dms/{system}/flags`, the `dms.document.flagged` webhook and the callback to the partner's URL (`{ \"flags\": [Flag] }`)." }, "FlagState": { "type": "string", "enum": [ "received", "posted", "rejected", "superseded" ], "description": "`received`: stored and passed the format checks. `posted`: posted in Mikono and, where money or stock moves, in QuickBooks. `rejected`: not posted, with a reason code. A QuickBooks failure after Mikono applied the document is also `rejected` (`R06` or `R09`); the Mikono posting stays and is not reversed. `superseded`: a newer version with another DMS status replaced it." }, "Gps": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [ "latitude", "longitude" ] }, "GpsInput": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [ "latitude", "longitude" ], "additionalProperties": false }, "Health": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "version": { "type": "string", "description": "API version (`info.version` of the OpenAPI document).", "examples": [ "1.0.0" ] }, "environment": { "type": "string", "enum": [ "test", "live" ], "description": "`test` on the sandbox deployment, `live` on production." }, "time": { "type": "string", "format": "date-time", "description": "Server time, ISO 8601 UTC." } }, "required": [ "status", "version", "environment", "time" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceNumber": { "type": "string" }, "status": { "type": "string", "description": "`draft`, `sent`, `viewed`, `partially_paid`, `paid`, `overdue` or `voided`.", "examples": [ "sent" ] }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/DocumentCustomer" }, { "type": "null" } ] }, "issueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date", "description": "The business date of the sale." }, "dueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date" }, "salesOrderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "locationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The warehouse or van the goods left from. A van means a van sale." }, "tripId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The delivery trip a van sale was made on." }, "salespersonId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who recorded the sale (the salesperson for Go van sales)." }, "paymentType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legacy payment type, when the invoice carries one. Payments: `GET /payments`." }, "pricesIncludeTax": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "true when line prices were quoted VAT-inclusive (van sales) and VAT was backed out; null on invoices older than this field." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" } }, "linesTruncated": { "type": "boolean", "description": "true when this document has more than 500 lines: only the first 500 are returned. A list page also stops early (`hasMore` true) rather than read more than about 2,500 child rows in all." }, "subtotal": { "$ref": "#/components/schemas/Money" }, "discountAmount": { "$ref": "#/components/schemas/Money" }, "taxAmount": { "$ref": "#/components/schemas/Money" }, "totalAmount": { "$ref": "#/components/schemas/Money" }, "balanceDue": { "$ref": "#/components/schemas/Money" }, "currency": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fiscal": { "$ref": "#/components/schemas/Fiscal" }, "posting": { "$ref": "#/components/schemas/Posting" }, "externalCodes": { "$ref": "#/components/schemas/ExternalCodes", "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "invoiceNumber", "status", "customer", "issueDate", "dueDate", "salesOrderId", "locationId", "tripId", "salespersonId", "paymentType", "pricesIncludeTax", "lines", "linesTruncated", "subtotal", "discountAmount", "taxAmount", "totalAmount", "balanceDue", "currency", "notes", "fiscal", "posting", "externalCodes", "createdAt", "updatedAt" ], "description": "`externalCodes.dms` is the DMS invoice number (`CS…`); `externalCodes.quickbooks` (read-only) the QuickBooks transaction id. `balanceDue` falls as payments and credit notes are applied, and each change moves `updatedAt`." }, "InvoiceCreate": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/RecordRefInput" }, "locationId": { "type": "string", "description": "The warehouse or van the goods leave from (`GET /locations`); required when a line sells a stock-tracked product. A van (`type: van`) makes this a van sale: the salesperson must be on an in-transit trip with that van for `issueDate`, else `422 no_open_trip`." }, "salespersonId": { "type": "string", "description": "The salesperson the sale is recorded for (`GET /salespeople`). Required for a van sale." }, "tripId": { "type": "string", "description": "The van sale's trip. Optional: without it Mikono finds the salesperson's in-transit trip for the van and date." }, "issueDate": { "type": "string", "format": "date", "description": "Business date of the sale. Defaults to today in the organisation's time zone; a van sale must fall on its trip's date." }, "dueDate": { "type": "string", "format": "date", "description": "Defaults to the issue date." }, "pricesIncludeTax": { "type": "boolean", "description": "true when `unitPrice` already contains VAT (Mikono backs it out, as Go van sales do). Defaults to the organisation's point-of-sale setting." }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceCreateLineInput" }, "description": "1 to 100 lines." } }, "required": [ "customer", "lines" ], "additionalProperties": false, "description": "An invoice to create and post: revenue and VAT, stock out of `locationId`, cost of sales. Open for payment (`POST /payments`)." }, "InvoiceCreateLineInput": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/RecordRefInput" }, "type": { "type": "string", "enum": [ "selling", "free_issue", "empties" ], "description": "`selling` (default); `free_issue`: goods given at no charge (posted to the promotions expense account, no price); `empties`: a returnable container product (crate, bottle) charged on the sale." }, "quantity": { "type": "number", "description": "In `unit`; more than zero." }, "unit": { "type": "string", "enum": [ "base", "pack" ], "description": "`base` (default): the product's stock unit; `pack`: its pack (case). A pack quantity is converted to stock units with the product's pack size, and a pack price is divided by it." }, "unitPrice": { "$ref": "#/components/schemas/MoneyInput" }, "discount": { "$ref": "#/components/schemas/MoneyInput" }, "taxRate": { "type": "number", "description": "VAT rate in percent. Defaults to the product's tax rate (0 when the organisation does not charge sales tax)." }, "description": { "type": "string" } }, "required": [ "product", "quantity" ], "additionalProperties": false, "description": "`unitPrice` is the price per `unit`: required on `selling` and `empties` lines (zero allowed on empties), not sent on a free issue. `discount` is an absolute line discount, at most quantity × unitPrice. Amounts are in the organisation's base currency." }, "InvoiceCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "invoice.created" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Invoice" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "InvoiceLine": { "type": "object", "properties": { "product": { "anyOf": [ { "$ref": "#/components/schemas/DocumentProduct" }, { "type": "null" } ], "description": "null on lines that name no product." }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "selling", "free_issue", "empties" ], "description": "`free_issue`: goods given at no charge; `empties`: a returnable container (crate, bottle) charged on the sale." }, "quantity": { "type": "number" }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product's unit." }, "unitPrice": { "$ref": "#/components/schemas/Money" }, "discount": { "$ref": "#/components/schemas/Money" }, "taxRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "VAT rate in percent." }, "tax": { "$ref": "#/components/schemas/Money" }, "amount": { "$ref": "#/components/schemas/Money" } }, "required": [ "product", "description", "type", "quantity", "unit", "unitPrice", "discount", "taxRate", "tax", "amount" ], "description": "`unitPrice` is the net price as posted (VAT backed out when the invoice's `pricesIncludeTax` is true); `amount` is quantity × unitPrice before discount and tax; `discount` is the line discount as quoted (on van sales the posted, tax-exclusive sum is the invoice's `discountAmount`)." }, "InvoicePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "InvoiceRefInput": { "type": "object", "properties": { "id": { "type": "string", "description": "Mikono id of the invoice." }, "code": { "type": "string", "description": "DMS code of the invoice.", "examples": [ "CS000123" ] } }, "additionalProperties": false, "description": "The invoice, by Mikono `id` or DMS `code`: send exactly one." }, "InvoiceUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "invoice.updated" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Invoice" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "InvoiceVoid": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why the invoice was voided; kept on the audit trail." } }, "additionalProperties": false, "description": "Send `{}` when there is no reason to record." }, "InvoiceVoidedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "invoice.voided" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Invoice" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "JourneyPlan": { "type": "object", "properties": { "routeId": { "type": "string" }, "routeCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "week": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Monday of the week the plan was evaluated for; null for the standing plan." }, "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "$ref": "#/components/schemas/DayOfWeek" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The date of this day in `week`; null without `week`." }, "outlets": { "type": "array", "items": { "type": "object", "properties": { "customerId": { "type": "string" }, "outletCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sequence": { "type": "number" }, "frequency": { "anyOf": [ { "$ref": "#/components/schemas/VisitFrequency" }, { "type": "null" } ] } }, "required": [ "customerId", "outletCode", "sequence", "frequency" ] } } }, "required": [ "day", "date", "outlets" ] } }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "routeId", "routeCode", "week", "days", "updatedAt" ], "description": "A route's standing journey plan: which outlets are visited on which weekday. With `week`, each day carries its date and only the stops due that date (biweekly and monthly cadence applied); one-week edits a manager makes to a rep's week in Mikono are not included." }, "JourneyPlanPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JourneyPlan" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "JourneyPlanUpsert": { "type": "object", "properties": { "routeCode": { "type": "string", "description": "The route's code. The route must exist (`PUT /routes/by-code/dms/{code}`)." }, "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "$ref": "#/components/schemas/DayOfWeekInput" }, "outlets": { "type": "array", "items": { "type": "object", "properties": { "outletCode": { "type": "string" }, "sequence": { "type": "number" } }, "required": [ "outletCode", "sequence" ], "additionalProperties": false } } }, "required": [ "day", "outlets" ], "additionalProperties": false } } }, "required": [ "routeCode", "days" ], "additionalProperties": false, "description": "Replaces the route's outlet list with the outlets in `days`: each outlet is visited weekly on the days it appears." }, "Location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "warehouse", "van", "damages", "other" ], "description": "`van` is a delivery truck." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vehicleRegistration": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "capacity": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "value", "unit" ] }, { "type": "null" } ] }, "homeWarehouseId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "address": { "anyOf": [ { "$ref": "#/components/schemas/LocationAddress" }, { "type": "null" } ] }, "externalCodes": { "$ref": "#/components/schemas/ExternalCodes", "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "description": "When the location last changed; null only on rows not yet backfilled." } }, "required": [ "id", "name", "type", "description", "vehicleRegistration", "capacity", "homeWarehouseId", "isActive", "isDefault", "address", "externalCodes", "createdAt", "updatedAt" ] }, "LocationAddress": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } }, "required": [ "addressLine1", "city", "country" ] }, "LocationAddressInput": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } }, "required": [ "addressLine1", "city", "country" ], "additionalProperties": false }, "LocationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "LocationUpsert": { "type": "object", "properties": { "name": { "type": "string", "description": "Required when the code is new." }, "type": { "type": "string", "enum": [ "warehouse", "van", "damages", "other" ], "description": "`van` is a delivery truck." }, "description": { "type": "string" }, "vehicleRegistration": { "type": "string" }, "isActive": { "type": "boolean" }, "address": { "$ref": "#/components/schemas/LocationAddressInput" } }, "additionalProperties": false }, "Me": { "type": "object", "properties": { "name": { "type": "string", "description": "The key's name, as set in Settings → Developers." }, "prefix": { "type": "string", "description": "First characters of the key, safe to display.", "examples": [ "mk_test_Ab12" ] }, "environment": { "type": "string", "enum": [ "test", "live" ], "description": "`test` on the sandbox deployment, `live` on production." }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "rateLimits": { "type": "object", "properties": { "read": { "$ref": "#/components/schemas/RateLimitBucket" }, "write": { "$ref": "#/components/schemas/RateLimitBucket" }, "ingest": { "$ref": "#/components/schemas/RateLimitBucket" } }, "required": [ "read", "write", "ingest" ], "description": "This key's token buckets. The operation's kind picks the bucket (`x-mikono-kind`). Defaults: read 600/min burst 100, write 120/min burst 30, ingest 60/min burst 60; Mikono can raise them per key." } }, "required": [ "name", "prefix", "environment", "organization", "scopes", "rateLimits" ] }, "Money": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,2})?$", "description": "Decimal string in major units, at most 2 decimals, no exponent.", "examples": [ "1254649.90" ] }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "examples": [ "UGX" ] } }, "required": [ "amount", "currency" ], "description": "A money amount. The amount is a string so client float handling cannot round it." }, "MoneyInput": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,2})?$", "description": "Decimal string in major units, at most 2 decimals, no exponent.", "examples": [ "1254649.90" ] }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "examples": [ "UGX" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "description": "A money amount. The amount is a string so client float handling cannot round it." }, "OpenApiDocument": { "description": "This OpenAPI 3.1 document." }, "Order": { "type": "object", "properties": { "id": { "type": "string" }, "orderNumber": { "type": "string" }, "status": { "type": "string", "description": "`draft`, `confirmed`, `processing`, `shipped`, `delivered`, `completed` or `cancelled`.", "examples": [ "confirmed" ] }, "source": { "type": "string", "enum": [ "api", "go", "web", "whatsapp", "dms" ], "description": "Where the order was taken: this API, the Go field app, the Mikono web app, a WhatsApp message, or the DMS." }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/DocumentCustomer" }, { "type": "null" } ] }, "orderDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date" }, "deliveryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date" }, "assignedRepId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The salesperson the order is assigned to." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLine" } }, "linesTruncated": { "type": "boolean", "description": "true when this document has more than 500 lines: only the first 500 are returned. A list page also stops early (`hasMore` true) rather than read more than about 2,500 child rows in all." }, "subtotal": { "$ref": "#/components/schemas/Money" }, "discountAmount": { "$ref": "#/components/schemas/Money" }, "taxAmount": { "$ref": "#/components/schemas/Money" }, "shippingAmount": { "$ref": "#/components/schemas/Money" }, "totalAmount": { "$ref": "#/components/schemas/Money" }, "currency": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The invoice the order was converted to." }, "externalCodes": { "$ref": "#/components/schemas/ExternalCodes", "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "orderNumber", "status", "source", "customer", "orderDate", "deliveryDate", "assignedRepId", "lines", "linesTruncated", "subtotal", "discountAmount", "taxAmount", "shippingAmount", "totalAmount", "currency", "notes", "invoiceId", "externalCodes", "createdAt", "updatedAt" ], "description": "A sales order (pre-order). `externalCodes.dms` is the RSS order number when the order came from or went to the DMS." }, "OrderCreate": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/CustomerRefInput" }, "orderDate": { "type": "string", "format": "date", "description": "Default: today (UTC)." }, "deliveryDate": { "type": "string", "format": "date" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLineCreateInput" }, "description": "1 to 100 lines." }, "externalCodes": { "type": "object", "properties": { "dms": { "type": "string" } }, "additionalProperties": false, "description": "The record's number in the DMS. A second create with the same code returns the first record (200) instead of creating another.", "examples": [ { "dms": "RSS000123" } ] } }, "required": [ "customer", "lines" ], "additionalProperties": false, "description": "A confirmed sales order. Mikono computes tax and totals from each product's tax rate; quantities are stored in base units." }, "OrderCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "order.created" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "OrderLine": { "type": "object", "properties": { "product": { "anyOf": [ { "$ref": "#/components/schemas/DocumentProduct" }, { "type": "null" } ], "description": "null on lines that name no product." }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Unit of measure as entered on the order." }, "unitPrice": { "$ref": "#/components/schemas/Money" }, "discount": { "$ref": "#/components/schemas/Money" }, "taxRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "VAT rate in percent." }, "tax": { "$ref": "#/components/schemas/Money" }, "amount": { "$ref": "#/components/schemas/Money" } }, "required": [ "product", "description", "quantity", "unit", "unitPrice", "discount", "taxRate", "tax", "amount" ], "description": "`amount` is the line total after the discount, including tax." }, "OrderLineCreateInput": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/ProductRefInput" }, "quantity": { "type": "number", "description": "In `unit`; whole numbers for products sold in packs.", "examples": [ 10 ] }, "unit": { "$ref": "#/components/schemas/OrderUnitInput" }, "unitPrice": { "$ref": "#/components/schemas/MoneyInput" }, "notes": { "type": "string" } }, "required": [ "product", "quantity" ], "additionalProperties": false, "description": "`unitPrice` is per `unit`, before tax, in the organisation's base currency. Omit it to use the customer's price-group price (the price the Mikono web app and Go quote)." }, "OrderPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "OrderStatusChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "order.status_changed" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "OrderUnitInput": { "type": "string", "enum": [ "case", "bottle", "piece" ], "description": "`case` is the product's pack (its pack size in base units); `bottle` and `piece` are base units. Default: base units." }, "OutletActivity": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "kind": { "type": "string", "description": "`competitor_activity`, `stock_photos`, `cooler_check`, `feedback` or `follow_up`." }, "recordedBy": { "type": "string" }, "tripId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tripStopId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "competitor": { "anyOf": [ { "type": "object", "properties": { "brand": { "type": "string" }, "activity": { "type": "string" }, "price": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "required": [ "brand", "activity", "price" ] }, { "type": "null" } ] }, "stock": { "anyOf": [ { "type": "object", "properties": { "area": { "type": "string" } }, "required": [ "area" ] }, { "type": "null" } ] }, "cooler": { "anyOf": [ { "type": "object", "properties": { "present": { "type": "boolean" }, "working": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "ownBrandOnly": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "branding": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "issue": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "present", "working", "ownBrandOnly", "branding", "issue" ] }, { "type": "null" } ] }, "feedback": { "anyOf": [ { "type": "object", "properties": { "topic": { "type": "string" }, "sentiment": { "type": "string" } }, "required": [ "topic", "sentiment" ] }, { "type": "null" } ] }, "followUp": { "anyOf": [ { "type": "object", "properties": { "reason": { "type": "string" }, "dueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "reason", "dueDate", "status", "resolvedAt" ] }, { "type": "null" } ] }, "photoUrls": { "type": "array", "items": { "type": "string" }, "description": "Present only when the key holds `customers:pii`. URLs expire." }, "gps": { "anyOf": [ { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [ "latitude", "longitude" ] }, { "type": "null" } ], "description": "Present only when the key holds `customers:pii`." }, "capturedAt": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "customerId", "kind", "recordedBy", "tripId", "tripStopId", "note", "competitor", "stock", "cooler", "feedback", "followUp", "capturedAt", "createdAt", "updatedAt" ], "description": "A report a salesperson made at an outlet." }, "OutletActivityPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OutletActivity" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "Payment": { "type": "object", "properties": { "id": { "type": "string" }, "paymentNumber": { "type": "string" }, "status": { "type": "string", "description": "`draft`, `pending_approval`, `approved`, `processing`, `recorded`, `reconciled`, `failed`, `void` or `returned`.", "examples": [ "recorded" ] }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/DocumentCustomer" }, { "type": "null" } ] }, "paymentDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date" }, "amount": { "$ref": "#/components/schemas/Money" }, "method": { "$ref": "#/components/schemas/PaymentMethod" }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cheque": { "anyOf": [ { "type": "object", "properties": { "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bank": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "open", "cleared", "bounced", "void" ] } }, "required": [ "number", "bank", "branch", "status" ] }, { "type": "null" } ], "description": "Cheque payments only. `number` is the payment reference; Mikono does not record the bank or branch yet." }, "cleared": { "type": "boolean" }, "salespersonId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who recorded the collection (the salesperson for Go collections)." }, "tripId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The delivery trip the collection was made on." }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAllocation" } }, "linesTruncated": { "type": "boolean", "description": "true when this document has more than 500 allocations: only the first 500 are returned. A list page also stops early (`hasMore` true) rather than read more than about 2,500 child rows in all." }, "unallocated": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Amount not allocated to an invoice, in the payment's currency; null when `unallocatedUnavailable` says why it cannot be computed." }, "unallocatedUnavailable": { "type": [ "string", "null" ], "enum": [ "missing_exchange_rate", "too_many_allocations", null ], "description": "`missing_exchange_rate`: an allocation is in another currency and Mikono holds no rate to convert it (never assumed 1); `too_many_allocations`: more than 500 allocations. null when `unallocated` is given." }, "currency": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "posting": { "$ref": "#/components/schemas/Posting" }, "externalCodes": { "$ref": "#/components/schemas/ExternalCodes", "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "paymentNumber", "status", "customer", "paymentDate", "amount", "method", "reference", "cheque", "cleared", "salespersonId", "tripId", "allocations", "linesTruncated", "unallocated", "unallocatedUnavailable", "currency", "notes", "posting", "externalCodes", "createdAt", "updatedAt" ], "description": "A customer payment (collection) and how it was allocated to invoices. `unallocated` is the part not allocated to an invoice (a prepayment), in the payment's currency: allocations in another currency are converted back at the rates stored with them. `externalCodes.dms` is the DMS payment number (`PY…`)." }, "PaymentAllocation": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "$ref": "#/components/schemas/Money" } }, "required": [ "invoiceId", "invoiceNumber", "amount" ], "description": "`amount` is in the invoice's currency, which can differ from the payment's." }, "PaymentAllocationCreateInput": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/InvoiceRefInput" }, "amount": { "$ref": "#/components/schemas/MoneyInput" } }, "required": [ "invoice", "amount" ], "additionalProperties": false, "description": "`amount` is in the payment's currency, which must be the invoice's currency." }, "PaymentCreate": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/CustomerRefInput" }, "paymentDate": { "type": "string", "format": "date", "description": "Default: today in the organisation's time zone." }, "amount": { "$ref": "#/components/schemas/MoneyInput" }, "method": { "type": "string", "enum": [ "cash", "cheque", "mobile_money", "card", "other" ], "description": "`bank_transfer` is not accepted yet: Mikono's collection core has no bank-transfer tender." }, "reference": { "type": "string", "description": "The cheque or mobile-money reference." }, "notes": { "type": "string" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAllocationCreateInput" }, "description": "1 to 50 allocations that add up to `amount`, each within its invoice's open balance." }, "externalCodes": { "type": "object", "properties": { "dms": { "type": "string" } }, "additionalProperties": false, "description": "The record's number in the DMS. A second create with the same code returns the first record (200) instead of creating another.", "examples": [ { "dms": "PY000123" } ] } }, "required": [ "customer", "amount", "method", "allocations" ], "additionalProperties": false, "description": "A customer payment (collection) allocated to invoices. Mikono records one receipt per allocation, as Go collections do, so each receipt posts to QuickBooks against its invoice." }, "PaymentCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "payment.created" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Payment" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "PaymentMethod": { "type": "string", "enum": [ "cash", "cheque", "mobile_money", "bank_transfer", "card", "other" ] }, "PaymentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "PaymentReceipts": { "type": "object", "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" }, "description": "One receipt per allocation, in allocation order." } }, "required": [ "payments" ] }, "PaymentReversedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "payment.reversed" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Payment" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "Posting": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_queued", "pending", "posted", "skipped", "failed", "cancelled" ], "description": "`not_queued`: QuickBooks posting is off or has not picked the document up; `pending`: queued or retrying; `posted`: in QuickBooks; `skipped`: deliberately not posted (`reason` says why); `failed`: needs attention in Mikono (Finance → Posting)." }, "quickbooksRef": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The QuickBooks transaction id once posted." }, "quickbooksType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The QuickBooks transaction type (`Invoice`, `SalesReceipt`, `Payment`, `CreditMemo` …)." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the document is skipped, failing or retrying." } }, "required": [ "status", "quickbooksRef", "quickbooksType", "reason" ], "description": "QuickBooks posting status. Posting runs in its own queue: a posting change does not move the document's `updatedAt`." }, "Price": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "productCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceGroup": { "type": "string", "description": "Price group (Mikono price tier), e.g. `retail`, `wholesale`, `hqrt`.", "examples": [ "retail" ] }, "unit": { "type": "string", "enum": [ "base", "pack" ], "description": "`base` prices one base unit (bottle, piece); `pack` prices one pack (case, crate)." }, "price": { "$ref": "#/components/schemas/Money" }, "minimumQuantity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "productId", "productCode", "priceGroup", "unit", "price", "minimumQuantity", "isDefault", "isActive", "createdAt", "updatedAt" ] }, "PricePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "PriceUpsertInput": { "type": "object", "properties": { "productCode": { "type": "string", "description": "The product's DMS code.", "examples": [ "780123" ] }, "priceGroup": { "type": "string" }, "unit": { "type": "string", "enum": [ "base", "pack" ], "description": "`base` prices one base unit (bottle, piece); `pack` prices one pack (case, crate)." }, "price": { "$ref": "#/components/schemas/MoneyInput" }, "isDefault": { "type": "boolean" }, "isActive": { "type": "boolean" } }, "required": [ "productCode", "priceGroup", "price" ], "additionalProperties": false, "description": "One price, keyed by product code, price group and unit. Mikono prices carry no effective dates; `effectiveFrom`/`effectiveTo` are refused." }, "PricesUpsert": { "type": "object", "properties": { "prices": { "type": "array", "items": { "$ref": "#/components/schemas/PriceUpsertInput" }, "description": "1 to 200 prices.", "minItems": 1, "maxItems": 200 } }, "required": [ "prices" ], "additionalProperties": false }, "PricesUpsertResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "created": { "type": "number" }, "updated": { "type": "number" }, "unchanged": { "type": "number" } }, "required": [ "data", "created", "updated", "unchanged" ] }, "Problem": { "type": "object", "description": "RFC 9457 problem details. `code` is stable; branch on it, not on `title` or `detail`.", "properties": { "type": { "type": "string", "format": "uri", "description": "Link to the error's documentation." }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "detail": { "type": "string" }, "requestId": { "type": "string", "description": "Same value as the `X-Request-Id` response header." }, "errors": { "type": "array", "description": "Field-level errors, when the problem concerns specific fields.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path to the field, e.g. `lines[3].productCode`." }, "code": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "field", "code", "detail" ] } } }, "required": [ "type", "title", "status", "code", "requestId" ] }, "Product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "packSize": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Base units per pack (bottles per case)." }, "packLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseUnitLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isReturnableContainer": { "type": "boolean" }, "containers": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "productCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantityPerUnit": { "type": "number" } }, "required": [ "productId", "productCode", "quantityPerUnit" ] }, "description": "Empties that travel with one base unit (bottle 1, crate 1/25)." }, "taxRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "VAT rate in percent." }, "priceIncludesVat": { "type": "boolean", "description": "Whether Mikono users enter this product's price VAT-inclusive. `price` is always VAT-exclusive." }, "price": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Base selling price, VAT-exclusive." }, "trackInventory": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalCodes": { "$ref": "#/components/schemas/ExternalCodes", "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "name", "description", "sku", "barcode", "unit", "packSize", "packLabel", "baseUnitLabel", "isReturnableContainer", "containers", "taxRate", "priceIncludesVat", "price", "trackInventory", "status", "category", "brand", "externalCodes", "createdAt", "updatedAt" ] }, "ProductCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "product.created" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Product" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "ProductPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "ProductRefInput": { "type": "object", "properties": { "id": { "type": "string", "description": "Mikono id of the product." }, "code": { "type": "string", "description": "DMS code of the product.", "examples": [ "780123" ] } }, "additionalProperties": false, "description": "The product, by Mikono `id` or DMS `code`: send exactly one." }, "ProductUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "product.updated" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Product" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "ProductUpsert": { "type": "object", "properties": { "name": { "type": "string", "description": "Required when the code is new." }, "description": { "type": "string" }, "sku": { "type": "string" }, "unit": { "type": "string" }, "packSize": { "type": "number" }, "packLabel": { "type": "string" }, "baseUnitLabel": { "type": "string" }, "price": { "$ref": "#/components/schemas/MoneyInput" }, "priceIncludesVat": { "type": "boolean" }, "trackInventory": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "category": { "type": "string" } }, "additionalProperties": false, "description": "Fields to set. Omitted fields keep their value on an existing product." }, "RateLimitBucket": { "type": "object", "properties": { "perMinute": { "type": "number", "description": "Tokens added per minute: the sustained request rate." }, "burst": { "type": "number", "description": "Bucket size: the most requests the key can send at once." } }, "required": [ "perMinute", "burst" ] }, "ReasonBody": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why; kept in the audit trail (and on the payment's notes for a reversal)." } }, "additionalProperties": false, "description": "Send `{}` when there is no reason to record." }, "ReasonCode": { "type": "string", "enum": [ "R01", "R02", "R03", "R04", "R05", "R06", "R07", "R08", "R09" ], "description": "Why a document was rejected. `R01` No customer code on the document; `R02` Reserved; an unknown product is held as R08; `R03` Set-up missing in Mikono: salesman, vendor, account or damages location not linked, a location inactive, or a DMS location record matching no Mikono location; `R04` Lines do not add up to the document total; `R05` Same document number already received with different content and the same DMS status; `R06` Accounting period closed in Mikono or QuickBooks; `R07` Document for another distributor code; `R08` Depends on a record not yet received or linked, such as an unknown customer, product, invoice, route or location code, or van stock not yet issued; `R09` Other. `R08` documents are held and retried for 48 hours, then rejected with `R08`." }, "RecordRefInput": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "description": "A record by its Mikono `id` or its DMS `code` (outlet code, SKU code). Send exactly one.", "examples": [ { "code": "UG2000001" } ] }, "Return": { "type": "object", "properties": { "id": { "type": "string" }, "returnNumber": { "type": "string" }, "status": { "type": "string", "description": "`requested`, `approved`, `received`, `processed`, `completed` or `rejected`." }, "returnType": { "type": "string" }, "reason": { "type": "string" }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/DocumentCustomer" }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sales_order", "invoice", "quotation" ] }, "id": { "type": "string" }, "number": { "type": "string" } }, "required": [ "type", "id", "number" ], "description": "The document the goods were sold on." }, "requestedDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date" }, "completedDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date" }, "toLocationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the goods were restocked." }, "creditNoteId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The credit note the return raised." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnLine" } }, "linesTruncated": { "type": "boolean", "description": "true when this document has more than 500 lines: only the first 500 are returned. A list page also stops early (`hasMore` true) rather than read more than about 2,500 child rows in all." }, "totalAmount": { "$ref": "#/components/schemas/Money" }, "refundAmount": { "$ref": "#/components/schemas/Money" }, "currency": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalCodes": { "$ref": "#/components/schemas/ExternalCodes", "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "returnNumber", "status", "returnType", "reason", "customer", "source", "requestedDate", "completedDate", "toLocationId", "creditNoteId", "lines", "linesTruncated", "totalAmount", "refundAmount", "currency", "notes", "externalCodes", "createdAt", "updatedAt" ], "description": "A customer return. `externalCodes.dms` is the DMS return number (`RT…`). DMS return numbers are not unique (the same number recurs across dates and outlets), so it identifies a return only together with its date and customer. There is no `GET /returns/by-code`; `?externalCode=dms:RT…` lists every return carrying that number." }, "ReturnCreate": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/RecordRefInput" }, "sourceInvoiceId": { "type": "string", "description": "The invoice the goods were sold on." }, "toLocationId": { "type": "string", "description": "The warehouse or van the goods come back to." }, "returnType": { "type": "string", "description": "Default `customer_return`." }, "reason": { "type": "string" }, "issueDate": { "type": "string", "format": "date", "description": "Business date of the credit. Defaults to today in the organisation's time zone." }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnCreateLineInput" }, "description": "1 to 100 lines. Goods are credited at the source invoice's price, discount share and VAT, as a Go stop return is; the invoice must still have that many units not yet credited. A returnable container (crate, bottle) is recorded as empties collected from the customer and goes back into stock at `toLocationId` at its cost price, with no credit, as Go records empties at a stop." } }, "required": [ "customer", "sourceInvoiceId", "toLocationId", "reason", "lines" ], "additionalProperties": false, "description": "Goods back from a customer, processed in one step: the return is recorded as completed and a return credit note is issued against the source invoice (stock back at the cost it left at, DR revenue + VAT / CR receivables, DR inventory / CR cost of sales)." }, "ReturnCreateLineInput": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/RecordRefInput" }, "quantity": { "type": "number", "description": "In `unit`; more than zero." }, "unit": { "type": "string", "enum": [ "base", "pack" ], "description": "`base` (default): the product's stock unit; `pack`: its pack (case). A pack quantity is converted to stock units with the product's pack size, and a pack price is divided by it." }, "condition": { "type": "string", "enum": [ "good", "damaged" ], "description": "`good` (default) goes back into stock at `toLocationId`; `damaged` is credited but not restocked." }, "reasonCode": { "type": "string" } }, "required": [ "product", "quantity" ], "additionalProperties": false }, "ReturnLine": { "type": "object", "properties": { "product": { "anyOf": [ { "$ref": "#/components/schemas/DocumentProduct" }, { "type": "null" } ], "description": "null on lines that name no product." }, "quantity": { "type": "number" }, "unitPrice": { "$ref": "#/components/schemas/Money" }, "amount": { "$ref": "#/components/schemas/Money" }, "reasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "condition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`new`, `used`, `damaged` or `defective`." }, "restockable": { "type": "boolean" } }, "required": [ "product", "quantity", "unitPrice", "amount", "reasonCode", "condition", "restockable" ] }, "ReturnPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Return" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "Route": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The route's code (DMS route or salesman code)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "territory": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "visitType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "defaultSalesRepId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultDriverId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultTruckLocationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalCodes": { "$ref": "#/components/schemas/ExternalCodes", "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "name", "code", "description", "territory", "visitType", "isActive", "defaultSalesRepId", "defaultDriverId", "defaultTruckLocationId", "externalCodes", "createdAt", "updatedAt" ], "description": "A route (beat): its outlets are `GET /routes/{id}/outlets`." }, "RouteOutlet": { "type": "object", "properties": { "customerId": { "type": "string" }, "outletCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sequence": { "type": "number" }, "isActive": { "type": "boolean" }, "daysOfWeek": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/DayOfWeek" } }, { "type": "null" } ] }, "frequency": { "anyOf": [ { "$ref": "#/components/schemas/VisitFrequency" }, { "type": "null" } ] }, "weekOfMonth": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Week of the month (1–5) for `monthly` stops." }, "anchorDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date", "description": "A date that fixes which alternate weeks a `biweekly` stop falls on." } }, "required": [ "customerId", "outletCode", "sequence", "isActive", "daysOfWeek", "frequency", "weekOfMonth", "anchorDate" ] }, "RouteOutlets": { "type": "object", "properties": { "routeId": { "type": "string" }, "routeCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outlets": { "type": "array", "items": { "$ref": "#/components/schemas/RouteOutlet" } } }, "required": [ "routeId", "routeCode", "outlets" ] }, "RouteOutletsUpsert": { "type": "object", "properties": { "outlets": { "type": "array", "items": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Mikono id; give this or `outletCode`." }, "outletCode": { "type": "string", "description": "The outlet's DMS code; give this or `customerId`." }, "sequence": { "type": "number" }, "isActive": { "type": "boolean" }, "daysOfWeek": { "type": "array", "items": { "$ref": "#/components/schemas/DayOfWeekInput" }, "description": "Required for every frequency except `daily`." }, "frequency": { "$ref": "#/components/schemas/VisitFrequencyInput" }, "weekOfMonth": { "type": "number", "description": "Required for `monthly`: week of the month, 1 to 5." }, "anchorDate": { "type": "string", "format": "date", "description": "Optional for `biweekly`: a date in a week the stop is visited, fixing the alternate weeks." } }, "required": [ "sequence" ], "additionalProperties": false }, "description": "The route's complete outlet list, replacing the current one. At most 2,000.", "maxItems": 2000 } }, "required": [ "outlets" ], "additionalProperties": false }, "RoutePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Route" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "RouteUpsert": { "type": "object", "properties": { "name": { "type": "string", "description": "Required when the code is new." }, "description": { "type": "string" }, "territory": { "type": "string" }, "visitType": { "type": "string" }, "isActive": { "type": "boolean" }, "defaultSalesRepId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A salesperson's id; null clears it." }, "defaultTruckLocationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A van's location id; null clears it." } }, "additionalProperties": false }, "Salesperson": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "personas": { "type": "array", "items": { "type": "string" } }, "salesmanCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultRouteId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only with the `customers:pii` scope." }, "externalCodes": { "$ref": "#/components/schemas/ExternalCodes", "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "name", "status", "personas", "salesmanCode", "defaultRouteId", "externalCodes", "createdAt", "updatedAt" ], "description": "A member holding the salesperson persona. Read-only: people join through invitations." }, "SalespersonPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Salesperson" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "SettlementClosedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "settlement.closed" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/TripSettlement" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "StockAdjustment": { "type": "object", "properties": { "id": { "type": "string" }, "adjustmentNumber": { "type": "string" }, "status": { "type": "string", "description": "`draft`, `approved`, `posted` or `cancelled`. API adjustments are `posted`." }, "adjustmentDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date" }, "reason": { "type": "string" }, "customReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "warehouse", "van", "damages", "other" ], "description": "`van` is a delivery truck." } }, "required": [ "id", "name", "type" ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/StockAdjustmentLine" } }, "totalValue": { "$ref": "#/components/schemas/Money" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalCodes": { "$ref": "#/components/schemas/ExternalCodes", "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "adjustmentNumber", "status", "adjustmentDate", "reason", "customReason", "location", "lines", "totalValue", "notes", "externalCodes", "createdAt", "updatedAt" ] }, "StockAdjustmentCreate": { "type": "object", "properties": { "locationId": { "type": "string", "description": "The warehouse or van (`GET /locations`)." }, "reason": { "$ref": "#/components/schemas/StockAdjustmentReasonInput" }, "customReason": { "type": "string" }, "adjustmentDate": { "type": "string", "format": "date", "description": "Defaults to today in the organisation's time zone." }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/StockAdjustmentCreateLineInput" }, "description": "1 to 100 lines, one per product." } }, "required": [ "locationId", "reason", "lines" ], "additionalProperties": false, "description": "A stock adjustment, posted at once: stock levels, cost layers and the inventory journal." }, "StockAdjustmentCreateLineInput": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/RecordRefInput" }, "quantity": { "type": "number", "description": "The change in `unit`: positive adds stock, negative removes it. Not zero." }, "unit": { "type": "string", "enum": [ "base", "pack" ], "description": "`base` (default): the product's stock unit; `pack`: its pack (case). A pack quantity is converted to stock units with the product's pack size, and a pack price is divided by it." }, "unitCost": { "$ref": "#/components/schemas/MoneyInput" } }, "required": [ "product", "quantity" ], "additionalProperties": false, "description": "`unitCost` (optional, only on a positive `quantity`) is the cost per stock unit of stock added, in the base currency; it defaults to the location's average cost, else the product's cost price. Stock taken out always leaves at the location's own valuation." }, "StockAdjustmentLine": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dmsCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product's DMS SKU code, when it has one." } }, "required": [ "id", "name", "sku", "dmsCode" ] }, "previousQuantity": { "type": "number" }, "newQuantity": { "type": "number" }, "quantity": { "type": "number", "description": "The change, in stock units." }, "unitCost": { "$ref": "#/components/schemas/Money" }, "totalCost": { "$ref": "#/components/schemas/Money" } }, "required": [ "product", "previousQuantity", "newQuantity", "quantity", "unitCost", "totalCost" ] }, "StockAdjustmentReasonInput": { "type": "string", "enum": [ "stock_count", "damage", "expiry", "theft", "shrinkage", "return_to_vendor", "production", "gift", "sample", "other" ], "description": "`other` needs `customReason`." }, "StockLevel": { "type": "object", "properties": { "id": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dmsCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product's DMS SKU code, when it has one." } }, "required": [ "id", "name", "sku", "dmsCode" ] }, "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "warehouse", "van", "damages", "other" ], "description": "`van` is a delivery truck." } }, "required": [ "id", "name", "type" ] }, "quantityOnHand": { "type": "number" }, "quantityAllocated": { "type": "number" }, "quantityAvailable": { "type": "number", "description": "On hand minus allocated." }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product's unit of measure." }, "batchNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "asOf": { "type": "string", "format": "date-time", "description": "When this level last changed (ISO 8601 UTC)." } }, "required": [ "id", "product", "location", "quantityOnHand", "quantityAllocated", "quantityAvailable", "unit", "batchNumber", "expiryDate", "asOf" ], "description": "Quantity of one product at one warehouse or van. A snapshot: levels carry no `updatedAt`, so `/stock-levels` does not take `updatedSince`; read `/stock-movements?since=` as the change feed." }, "StockLevelPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StockLevel" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "StockMovement": { "type": "object", "properties": { "id": { "type": "string" }, "transactionNumber": { "type": "string" }, "date": { "type": "string", "description": "The movement's date as Mikono stored it (ISO 8601)." }, "type": { "type": "string", "enum": [ "purchase", "sale", "adjustment", "transfer", "return_from_customer", "return_to_vendor", "production_in", "production_out" ], "description": "What moved the stock." }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dmsCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product's DMS SKU code, when it has one." } }, "required": [ "id", "name", "sku", "dmsCode" ] }, "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "warehouse", "van", "damages", "other" ], "description": "`van` is a delivery truck." } }, "required": [ "id", "name", "type" ] }, "fromLocation": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "warehouse", "van", "damages", "other" ], "description": "`van` is a delivery truck." } }, "required": [ "id", "name", "type" ] }, { "type": "null" } ] }, "toLocation": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "warehouse", "van", "damages", "other" ], "description": "`van` is a delivery truck." } }, "required": [ "id", "name", "type" ] }, { "type": "null" } ] }, "quantity": { "type": "number", "description": "Signed: negative when stock left `location`." }, "unitCost": { "$ref": "#/components/schemas/Money" }, "reference": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "id", "number" ] }, { "type": "null" } ], "description": "The document that moved the stock (`invoice`, `transfer`, `adjustment`, …)." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Adjustment reason, for adjustments." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono recorded the movement. `since` compares against this." } }, "required": [ "id", "transactionNumber", "date", "type", "product", "location", "fromLocation", "toLocation", "quantity", "reference", "reason", "createdAt" ], "description": "One stock movement. Movements are never edited; corrections are new movements. `unitCost` is present only when the key also holds `payments:read`." }, "StockMovementCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "stock.movement.created" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/StockMovementDocument" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "StockMovementDocument": { "type": "object", "properties": { "id": { "type": "string", "description": "The source document's Mikono id (`reference.id`), else the single movement's id." }, "reference": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "id", "number" ] }, { "type": "null" } ], "description": "The document that moved the stock (`invoice`, `transfer`, `adjustment`, …)." }, "date": { "type": "string", "description": "The first movement's date as Mikono stored it (ISO 8601)." }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/StockMovement" }, "description": "The document's movements, as `GET /stock-movements` returns them, without `unitCost` (at most 1,500)." }, "movementsTruncated": { "type": "boolean", "description": "True when movements were left out to keep one delivery under 1,500 movements, 256 KB and one step's read budget; read the rest from `GET /stock-movements`." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono recorded the first movement (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When Mikono recorded the last movement (ISO 8601 UTC). Movements are never edited." } }, "required": [ "id", "reference", "date", "movements", "movementsTruncated", "createdAt", "updatedAt" ], "description": "The stock movements of one inventory document." }, "StockMovementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StockMovement" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "StockTransfer": { "type": "object", "properties": { "id": { "type": "string" }, "transferNumber": { "type": "string" }, "status": { "type": "string", "description": "`draft`, `approved`, `completed` or `cancelled`. API transfers are `completed`." }, "transferDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date" }, "from": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "warehouse", "van", "damages", "other" ], "description": "`van` is a delivery truck." } }, "required": [ "id", "name", "type" ] }, "to": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "warehouse", "van", "damages", "other" ], "description": "`van` is a delivery truck." } }, "required": [ "id", "name", "type" ] }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/StockTransferLine" } }, "totalValue": { "$ref": "#/components/schemas/Money" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalCodes": { "$ref": "#/components/schemas/ExternalCodes", "description": "Codes this record carries in other systems, keyed by system: `dms` and registered partner systems are writable; `quickbooks` and `efris` are read-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "transferNumber", "status", "transferDate", "from", "to", "reference", "lines", "totalValue", "notes", "externalCodes", "createdAt", "updatedAt" ] }, "StockTransferCreate": { "type": "object", "properties": { "fromLocationId": { "type": "string" }, "toLocationId": { "type": "string" }, "transferDate": { "type": "string", "format": "date", "description": "Defaults to today in the organisation's time zone." }, "reference": { "type": "string" }, "notes": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/StockTransferCreateLineInput" }, "description": "1 to 100 lines, one per product. Moved at the source location's cost." } }, "required": [ "fromLocationId", "toLocationId", "lines" ], "additionalProperties": false, "description": "A transfer between two locations, completed at once." }, "StockTransferCreateLineInput": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/RecordRefInput" }, "quantity": { "type": "number", "description": "In `unit`; more than zero." }, "unit": { "type": "string", "enum": [ "base", "pack" ], "description": "`base` (default): the product's stock unit; `pack`: its pack (case). A pack quantity is converted to stock units with the product's pack size, and a pack price is divided by it." } }, "required": [ "product", "quantity" ], "additionalProperties": false }, "StockTransferLine": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dmsCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product's DMS SKU code, when it has one." } }, "required": [ "id", "name", "sku", "dmsCode" ] }, "quantity": { "type": "number", "description": "In stock units." }, "unitCost": { "$ref": "#/components/schemas/Money" }, "totalCost": { "$ref": "#/components/schemas/Money" } }, "required": [ "product", "quantity", "unitCost", "totalCost" ] }, "Tombstone": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the record was deleted (ISO 8601 UTC)." } }, "required": [ "id", "deleted", "deletedAt" ], "description": "A deleted record, returned only with `includeDeleted=true`." }, "Trip": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date", "examples": [ "2026-10-02" ] }, "status": { "type": "string", "enum": [ "planning", "loading", "in_transit", "reconciling", "closed", "cancelled" ], "description": "`reconciling`: back at the depot, settlement open. `closed`: settled." }, "route": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The route's DMS code." } }, "required": [ "id", "name", "code" ] }, "truck": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vehicleRegistration": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "vehicleRegistration" ] }, "warehouseId": { "type": "string" }, "crew": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "description": "`driver`, `sales_rep`, `helper` or `driver_sales_rep`." } }, "required": [ "userId", "name", "role" ] } }, "startTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "closedForFinanceAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set when the back office closed the trip without a stock count." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." }, "stops": { "type": "object", "properties": { "planned": { "type": "number", "description": "Every stop on the trip." }, "done": { "type": "number", "description": "Delivered, partly delivered or collected." }, "missed": { "type": "number", "description": "Skipped or failed." }, "pending": { "type": "number", "description": "Not yet worked." } }, "required": [ "planned", "done", "missed", "pending" ], "description": "Stop counts." }, "loads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "noteNumber": { "type": "string", "description": "Goods Issued Note number." }, "direction": { "type": "string", "description": "`warehouse_to_truck` or `truck_to_truck`." }, "status": { "type": "string", "description": "`issued`, `attested`, `disputed` or `void`." }, "issuedAt": { "type": "string" }, "attestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dmsCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product's DMS SKU code, when it has one." } }, "required": [ "id", "name", "sku", "dmsCode" ] }, "issuedQty": { "type": "number" }, "attestedQty": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "product", "issuedQty", "attestedQty" ] } } }, "required": [ "id", "noteNumber", "direction", "status", "issuedAt", "attestedAt", "lines" ] } }, "returns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "description": "`submitted`, `accepted`, `rejected` or `withdrawn`." }, "requestedAt": { "type": "string" }, "reviewedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dmsCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product's DMS SKU code, when it has one." } }, "required": [ "id", "name", "sku", "dmsCode" ] }, "returnedQty": { "type": "number" }, "acceptedQty": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "damagedQty": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "product", "returnedQty", "acceptedQty", "damagedQty" ] } } }, "required": [ "id", "status", "requestedAt", "reviewedAt", "lines" ] } } }, "required": [ "id", "date", "status", "route", "truck", "warehouseId", "crew", "startTime", "endTime", "cancelledAt", "closedForFinanceAt", "createdAt", "updatedAt", "stops", "loads", "returns" ] }, "TripClosedEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Delivery is at-least-once: deduplicate on it.", "examples": [ "evt_k3m9q2x7c4v8b1n5h6j0r2t4" ] }, "type": { "type": "string", "const": "trip.closed" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was recorded (ISO 8601 UTC)." }, "apiVersion": { "type": "string", "const": "v1" }, "organizationId": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Trip" }, { "$ref": "#/components/schemas/DeletedRecord" }, { "$ref": "#/components/schemas/TruncatedRecord" } ] } }, "required": [ "object" ] } }, "required": [ "id", "type", "createdAt", "apiVersion", "organizationId", "data" ] }, "TripLocation": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time", "examples": [ "2026-10-02T07:15:00.000Z" ] }, "userId": { "type": "string" }, "gps": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [ "latitude", "longitude" ], "description": "Present only when the key holds `customers:pii`." }, "accuracyMeters": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "speedKph": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "headingDegrees": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "source": { "type": "string" } }, "required": [ "timestamp", "userId", "accuracyMeters", "speedKph", "headingDegrees", "source" ], "description": "One GPS ping from the crew's phone." }, "TripLocationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TripLocation" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "TripPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TripSummary" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "TripSettlement": { "type": "object", "properties": { "tripId": { "type": "string" }, "date": { "type": "string", "format": "date", "examples": [ "2026-10-02" ] }, "status": { "type": "string", "enum": [ "planning", "loading", "in_transit", "reconciling", "closed", "cancelled" ], "description": "`reconciling`: back at the depot, settlement open. `closed`: settled." }, "routeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "salesValue": { "$ref": "#/components/schemas/Money" }, "discount": { "$ref": "#/components/schemas/Money" }, "creditSales": { "$ref": "#/components/schemas/Money" }, "nonCashCollections": { "$ref": "#/components/schemas/Money" }, "prepayments": { "$ref": "#/components/schemas/Money" }, "debtCollectionsCash": { "$ref": "#/components/schemas/Money" }, "creditNotes": { "$ref": "#/components/schemas/Money" }, "cashRefunds": { "$ref": "#/components/schemas/Money" }, "cashExpenses": { "$ref": "#/components/schemas/Money" }, "cashExpectedFromSales": { "$ref": "#/components/schemas/Money" }, "floatIssued": { "$ref": "#/components/schemas/Money" }, "cashExpected": { "$ref": "#/components/schemas/Money" }, "cashCounted": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "The depot's count; null until counted." }, "variance": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Cash expected minus cash counted; positive is a shortage. Null until counted." }, "varianceReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mobileMoney": { "$ref": "#/components/schemas/Money" }, "credit": { "$ref": "#/components/schemas/Money" }, "collected": { "$ref": "#/components/schemas/Money" }, "stockVarianceValue": { "$ref": "#/components/schemas/Money" }, "stockReconciliation": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dmsCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The product's DMS SKU code, when it has one." } }, "required": [ "id", "name", "sku", "dmsCode" ] }, "loaded": { "type": "number" }, "delivered": { "type": "number" }, "vanSold": { "type": "number" }, "freeIssued": { "type": "number" }, "returned": { "type": "number" }, "expectedRemaining": { "type": "number" }, "variance": { "type": "number", "description": "Counted minus expected units; negative is short." }, "salesValue": { "$ref": "#/components/schemas/Money" }, "varianceValue": { "$ref": "#/components/schemas/Money" } }, "required": [ "product", "loaded", "delivered", "vanSold", "freeIssued", "returned", "expectedRemaining", "variance", "salesValue", "varianceValue" ] } }, "closedForFinance": { "type": "boolean", "description": "Closed without a stock count; returns are what the truck ledger held." }, "closedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "tripId", "date", "status", "routeName", "salesValue", "discount", "creditSales", "nonCashCollections", "prepayments", "debtCollectionsCash", "creditNotes", "cashRefunds", "cashExpenses", "cashExpectedFromSales", "floatIssued", "cashExpected", "cashCounted", "variance", "varianceReason", "mobileMoney", "credit", "collected", "stockVarianceValue", "stockReconciliation", "closedForFinance", "closedAt", "updatedAt" ], "description": "The depot settlement sheet's figures for one trip, computed by the same code as the settlement screen. `salesValue`: delivered and van-sale lines before discount. `creditSales`: unpaid same-trip invoices plus delivered-on-account value. `nonCashCollections`: same-trip receipts by mobile money, cheque, card or bank. `prepayments`: cash against no invoice. `debtCollectionsCash`: cash against invoices from before the trip. `cashExpected`: cash expected from sales plus the float. `mobileMoney`: mobile money collected on the trip. `credit`: balance still due on the trip's own invoices. `collected`: every collection, any tender. `stockVarianceValue`: the product rows' variance value." }, "TripSettlementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TripSettlement" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] }, "TripSummary": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date", "examples": [ "2026-10-02" ] }, "status": { "type": "string", "enum": [ "planning", "loading", "in_transit", "reconciling", "closed", "cancelled" ], "description": "`reconciling`: back at the depot, settlement open. `closed`: settled." }, "route": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The route's DMS code." } }, "required": [ "id", "name", "code" ] }, "truck": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vehicleRegistration": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "vehicleRegistration" ] }, "warehouseId": { "type": "string" }, "crew": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "description": "`driver`, `sales_rep`, `helper` or `driver_sales_rep`." } }, "required": [ "userId", "name", "role" ] } }, "startTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "closedForFinanceAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set when the back office closed the trip without a stock count." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Mikono created the record (ISO 8601 UTC)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "date", "status", "route", "truck", "warehouseId", "crew", "startTime", "endTime", "cancelledAt", "closedForFinanceAt", "createdAt", "updatedAt" ], "description": "A trip as lists return it. `GET /trips/{id}` adds stops, loads and returns." }, "TruncatedRecord": { "type": "object", "properties": { "id": { "type": "string" }, "truncated": { "type": "boolean", "const": true }, "reason": { "type": "string", "enum": [ "reads", "bytes" ], "description": "`reads`: building it would read too many rows in one step; `bytes`: it is larger than 256 KB." }, "fetch": { "type": "string", "description": "The endpoint that returns the full record, e.g. `GET /trips/{id}/settlement`." }, "summary": { "type": "object", "additionalProperties": {}, "description": "Header fields as stored (number, status, dates, currency, totals); never computed. A string longer than 1 KB is cut and ends with `…`." }, "summaryTruncated": { "type": "boolean", "const": true, "description": "Present when a `summary` string was cut at 1 KB or a header field was left out to keep the record within 256 KB." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC)." } }, "required": [ "id", "truncated", "reason", "fetch", "summary", "updatedAt" ], "description": "Sent instead of the record when the full object does not fit one delivery." }, "Visit": { "type": "object", "properties": { "id": { "type": "string", "description": "Mikono id of the visit." }, "date": { "type": "string", "format": "date", "examples": [ "2026-10-02" ] }, "salesperson": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "routeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "planned": { "type": "boolean", "description": "On the salesperson's plan for the day." }, "state": { "type": "string", "enum": [ "visited", "skipped_with_reason", "not_visited", "open", "off_plan" ], "description": "`open`: planned for today or later and not visited yet. `off_plan`: visited without being planned." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why a planned visit was missed, when the rep gave one." }, "status": { "type": "string" }, "checkInTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "checkOutTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO 8601 UTC). Pass the last one you saw as `updatedSince`." } }, "required": [ "id", "date", "salesperson", "customerId", "customerName", "routeId", "planned", "state", "reason", "status", "checkInTime", "checkOutTime", "outcome", "updatedAt" ], "description": "A planned or off-plan outlet visit, classified the way the journey-plan adherence report does." }, "VisitFrequency": { "type": "string", "enum": [ "daily", "weekly", "biweekly", "monthly" ] }, "VisitFrequencyInput": { "type": "string", "enum": [ "daily", "weekly", "biweekly", "monthly" ] }, "VisitPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Visit" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` to fetch the next page; null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] } }, "parameters": { "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's `nextCursor`.", "schema": { "type": "string" } }, "ExternalCode": { "name": "externalCode", "in": "query", "required": false, "description": "Filter by an external code, written `:` (for example `dms:UG2000123`).", "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1–255 characters, unique per logical request. A retry with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body returns `422 idempotency_key_reused`. Keys expire after 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "Page size. Default 50, maximum 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "UpdatedSince": { "name": "updatedSince", "in": "query", "required": false, "description": "Return records whose `updatedAt` is at or after this ISO 8601 UTC time, oldest first: a resumable change feed. A write can become visible a few seconds after its `updatedAt`, so a record changed during your read can appear after you have paged past its time. To never miss a change, start each poll from your last checkpoint minus an overlap of 5 minutes and skip records whose id and `updatedAt` you have already processed. Records can therefore repeat. For real-time changes, subscribe to webhooks.", "schema": { "type": "string", "format": "date-time" } } }, "headers": { "RateLimitLimit": { "description": "Requests allowed in the current window for this key and bucket.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "XRequestId": { "description": "Request id; echoes a valid client-sent `X-Request-Id`, otherwise generated. Quote it to support.", "schema": { "type": "string" } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from Settings → Developers, sent as `Authorization: Bearer `. Sandbox keys start `mk_test_` and work only on the sandbox deployment; production keys start `mk_live_`. Keys in the query string are refused (`400 key_in_query`)." } } } }