{ "openapi": "3.0.3", "info": { "title": "Chomoka Marketplace API", "version": "1.0.0", "description": "How the Chomoka app, suppliers and offtakers integrate with the Chomoka Marketplace. Amounts are whole numbers in the group's currency; times are ISO 8601 UTC. Errors are always {error: {code, message, details}}." }, "servers": [ { "url": "https://market.stg.chomoka.org/api/inputmarket/v1", "description": "Staging" } ], "tags": [ { "name": "Start-up and context" }, { "name": "Phone checks" }, { "name": "Catalogue" }, { "name": "Cart, members and consent" }, { "name": "Orders" }, { "name": "Loan offer and signing" }, { "name": "Delivery and photos" }, { "name": "Loans and repayments" }, { "name": "Offline sync" }, { "name": "Agent sessions" }, { "name": "Farm records" }, { "name": "Harvest sales (group side)" }, { "name": "Supplier API" }, { "name": "Offtaker API" }, { "name": "Payment results webhook" } ], "paths": { "/ping": { "get": { "tags": [ "Start-up and context" ], "summary": "Health check and the server clock", "description": "Health check and the server clock. Use `server_time` to correct the phone's clock before recording offline actions.", "operationId": "get_ping", "security": [], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "ok": true, "server_time": "2026-11-06T16:17:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/me/context": { "get": { "tags": [ "Start-up and context" ], "summary": "Everything the home screen needs: the group and its location, eligibility, credit, wallet, allowed payment methods, cons", "description": "Everything the home screen needs: the group and its location, eligibility, credit, wallet, allowed payment methods, consent status, counts of things waiting for the group, the officers who sign, and the limits the app applies before calling the server (`config`). With an Agent signed in, `user` and `agent` describe the Agent.", "operationId": "get_me_context", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "group": { "id": "g-100", "name": "Women's Maize Group", "country": "UG", "location": { "region": "Central", "district": "Mukono", "subcounty": "Goma", "parish": "Seeta", "village": "Bajjo" }, "geo": { "lat": 0.3601, "lng": 32.7514 } }, "user": { "id": null, "role": "GROUP", "name": "Women's Maize Group" }, "agent": null, "eligible": true, "ineligible_reason": null, "capabilities": [ "order.create", "offer.sign" ], "credit": { "limit": 5000000, "used": 0, "reserved": 0, "available": 5000000 }, "wallet": { "balance": 450000, "held": 0, "available": 450000, "has_wallet": true }, "payment_methods": [ "LOAN", "WALLET" ], "consent": { "accepted": false, "version": "2", "current_version": "2" }, "action_counts": { "offers_to_review": 0, "deliveries_to_confirm": 0 }, "contacts": [ { "id": "101", "kind": "ACCOUNT_OWNER", "name": "Mary Akello", "role": "CHAIRPERSON", "phone": "+256 7•• ••• 101" }, { "id": "102", "kind": "LOAN_CONTACT", "name": "Grace Nakato", "role": "TREASURER", "phone": "+256 7•• ••• 102" } ], "farm": { "completeness_pct": 0, "plots_count": 0, "expected_kg": 0 }, "unsent_photo_alert": null, "unsent_photo_alert_days": 7, "product_name": "Marketplace", "config": { "allocation": { "require_mapped_plot": false }, "consent": { "witnessed_max_amount": 300000, "require_agent": false }, "farm": { "buyer_visibility_min_percent": 80, "area_match_tolerance_percent": 20, "gps_max_accuracy_m": null, "checkin_required_photos": null }, "agent": { "session_minutes": 30 } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/config": { "get": { "tags": [ "Start-up and context" ], "summary": "All runtime settings for this group: currency, feature switches, cart limits, offer and delivery rules, dispute reasons,", "description": "All runtime settings for this group: currency, feature switches, cart limits, offer and delivery rules, dispute reasons, support contacts, texts, evidence policies, consent methods, OTP and offline settings. Large; cache it and send `If-None-Match` with the last `ETag` to get `304 Not Modified`.", "operationId": "get_config", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/credit": { "get": { "tags": [ "Start-up and context" ], "summary": "The group's Marketplace credit on its own: limit, used by running loans, reserved by open orders, available.", "description": "The group's Marketplace credit on its own: limit, used by running loans, reserved by open orders, available.", "operationId": "get_credit", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "limit": 5000000, "used": 0, "reserved": 0, "available": 5000000 } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/consent": { "post": { "tags": [ "Start-up and context" ], "summary": "Records that the group accepted the Marketplace terms", "description": "Records that the group accepted the Marketplace terms. Send the `current_version` from `/me/context`.", "operationId": "post_consent", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "description": "The consent text version shown to the group." } }, "required": [ "version" ] } } } } } }, "/devices": { "post": { "tags": [ "Start-up and context" ], "summary": "Registers the phone (push token, app version)", "description": "Registers the phone (push token, app version). Optional.", "operationId": "post_devices", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/notifications": { "get": { "tags": [ "Start-up and context" ], "summary": "Messages for the group, newest first, paged.", "description": "Messages for the group, newest first, paged.", "operationId": "get_notifications", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page, from 1." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Items per page (default 20)." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [], "meta": { "page": 1, "per_page": 20, "total": 0 } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/notifications/{id}/read": { "post": { "tags": [ "Start-up and context" ], "summary": "Marks one notification read.", "description": "Marks one notification read.", "operationId": "post_notifications_id_read", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/phone-checks": { "post": { "tags": [ "Phone checks" ], "summary": "Sends a code to the phone", "description": "Sends a code to the phone. `purpose` is one of `DRIVER`, `PICKUP_REP`, `DELIVERY_RECEIVER`, `TEAM_MEMBER`, `COMPANY_CONTACT`, `JOIN`.", "operationId": "post_phone_checks", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "purpose": { "type": "string", "description": "What the phone is for." }, "phone": { "type": "string", "description": "International, or local for `country`." }, "country": { "type": "string", "description": "ISO code for a local number." }, "name": { "type": "string", "description": "The full name of the person who uses the phone, as on their mobile money account." } }, "required": [ "purpose", "phone", "name" ] } } } } } }, "/phone-checks/{id}/confirm": { "post": { "tags": [ "Phone checks" ], "summary": "Checks the code, then the mobile money name", "description": "Checks the code, then the mobile money name. `VERIFIED` returns the `token`. `NAME_MISMATCH` returns the registered name and no token: ask for a phone in the right name, or save the phone under the registered name. If the wallet service does not answer you get `503` with `details.retry_without_code: true`; call again without a code. A number with no mobile money account returns `422`.", "operationId": "post_phone_checks_id_confirm", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "The code sent to the phone. Leave it out when retrying after a 503." } }, "required": [ "code" ] } } } } } }, "/phone-checks/{id}/use-registered-name": { "post": { "tags": [ "Phone checks" ], "summary": "After `NAME_MISMATCH`: confirms the phone under the name on its mobile money account", "description": "After `NAME_MISMATCH`: confirms the phone under the name on its mobile money account. The returned `name` is what will be saved, whatever name the form sends.", "operationId": "post_phone_checks_id_use_registered_name", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/provider/phone-checks": { "post": { "tags": [ "Phone checks" ], "summary": "Same as `POST /phone-checks`, for supplier integrations (drivers, team members, company contact).", "description": "Same as `POST /phone-checks`, for supplier integrations (drivers, team members, company contact).", "operationId": "post_provider_phone_checks", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/provider/phone-checks/{id}/confirm": { "post": { "tags": [ "Phone checks" ], "summary": "Same as `POST /phone-checks/{id}/confirm`.", "description": "Same as `POST /phone-checks/{id}/confirm`.", "operationId": "post_provider_phone_checks_id_confirm", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtaker/phone-checks": { "post": { "tags": [ "Phone checks" ], "summary": "Same as `POST /phone-checks`, for offtaker integrations (pickup reps).", "description": "Same as `POST /phone-checks`, for offtaker integrations (pickup reps).", "operationId": "post_offtaker_phone_checks", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtaker/phone-checks/{id}/confirm": { "post": { "tags": [ "Phone checks" ], "summary": "Same as `POST /phone-checks/{id}/confirm`.", "description": "Same as `POST /phone-checks/{id}/confirm`.", "operationId": "post_offtaker_phone_checks_id_confirm", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/categories": { "get": { "tags": [ "Catalogue" ], "summary": "Product categories.", "description": "Product categories.", "operationId": "get_categories", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": [ { "id": "a32964e9-cc8a-4c24-83fe-ea7c8267876f", "code": "seeds", "name": "Seeds", "icon_url": null, "parent_id": null }, { "id": "a32964e9-cde3-4bc5-8c92-111745620485", "code": "fertiliser", "name": "Fertiliser", "icon_url": null, "parent_id": null } ] } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products": { "get": { "tags": [ "Catalogue" ], "summary": "Products the group can order, from suppliers serving its country and district.", "description": "Products the group can order, from suppliers serving its country and district.\n\n**Product photos.** `images` lists every photo, cover first: `{url, thumb_url, width, height}`. `url` is a 1024 × 1024 JPEG and `thumb_url` a 320 × 320 JPEG. URLs never change, so cache them. `image_urls` (large URLs only) stays for older app versions.", "operationId": "get_products", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "category_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only this category." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by name." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sort order." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Ask for a paged `{data, meta}` response." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Ask for a paged `{data, meta}` response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": [ { "id": "a32964e9-d193-4057-a886-2f8ac0970869", "provider": { "id": "a32964e9-ce56-46db-bac9-00e337495b2c", "name": "Agro Supply", "logo_url": null }, "category_id": "a32964e9-cc8a-4c24-83fe-ea7c8267876f", "name": "Bean seed", "description": null, "unit": { "code": "kg", "name": "Kilogram" }, "unit_price": 6000, "availability": "IN_STOCK", "min_qty": 1, "max_qty": 500, "qty_step": 1, "image_urls": [], "images": [], "delivery_terms": null }, { "id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "provider": { "id": "a32964e9-ce56-46db-bac9-00e337495b2c", "name": "Agro Supply", "logo_url": null }, "category_id": "a32964e9-cde3-4bc5-8c92-111745620485", "name": "DAP fertiliser 50 kg", "description": null, "unit": { "code": "bag", "name": "Bag" }, "unit_price": 185000, "availability": "IN_STOCK", "min_qty": 1, "max_qty": 100, "qty_step": 1, "image_urls": [], "images": [], "delivery_terms": null } ] } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products/{id}": { "get": { "tags": [ "Catalogue" ], "summary": "One product.", "description": "One product.", "operationId": "get_products_id", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "provider": { "id": "a32964e9-ce56-46db-bac9-00e337495b2c", "name": "Agro Supply", "logo_url": null }, "category_id": "a32964e9-cc8a-4c24-83fe-ea7c8267876f", "name": "Maize seed (Longe 5)", "description": "Open-pollinated maize.", "unit": { "code": "kg", "name": "Kilogram" }, "unit_price": 105000, "availability": "IN_STOCK", "min_qty": 1, "max_qty": 500, "qty_step": 1, "image_urls": [], "images": [], "delivery_terms": "3 to 5 days." } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/providers": { "get": { "tags": [ "Catalogue" ], "summary": "Suppliers the group can buy from.", "description": "Suppliers the group can buy from.", "operationId": "get_providers", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": [ { "id": "a32964e9-ce56-46db-bac9-00e337495b2c", "name": "Agro Supply", "logo_url": null } ] } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/providers/{id}": { "get": { "tags": [ "Catalogue" ], "summary": "One supplier.", "description": "One supplier.", "operationId": "get_providers_id", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/cart/quote": { "post": { "tags": [ "Cart, members and consent" ], "summary": "Prices a cart without saving it", "description": "Prices a cart without saving it. Returns one order per supplier, the wallet/loan split, the lender, and whether the group's credit covers it (`exceeds_limit`, `shortfall`).", "operationId": "post_cart_quote", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "orders": [ { "provider_id": "a32964e9-ce56-46db-bac9-00e337495b2c", "provider": { "id": "a32964e9-ce56-46db-bac9-00e337495b2c", "name": "Agro Supply", "logo_url": null }, "lines": [ { "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "name": "Maize seed (Longe 5)", "unit": "kg", "qty": 10, "unit_price": 105000, "line_total": 1050000, "availability": "IN_STOCK" }, { "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "name": "DAP fertiliser 50 kg", "unit": "bag", "qty": 2, "unit_price": 185000, "line_total": 370000, "availability": "IN_STOCK" } ], "total": 1420000, "wallet_amount": 0, "loan_amount": 1420000, "funder": { "id": "a32964e9-ea4c-417b-9286-4b1d5a4ba144", "name": "Ensibuuko Finance", "available": true } } ], "grand_total": 1420000, "total": 1420000, "payment": { "method": "LOAN", "wallet_amount": 0, "loan_amount": 1420000 }, "wallet_amount": 0, "loan_amount": 1420000, "wallet_balance_after": 450000, "credit_after": 3580000, "credit": { "limit": 5000000, "used": 0, "reserved": 0, "available": 5000000, "after": 3580000, "exceeds": false, "shortfall": 0, "suggested_max_total": 5000000 }, "available_after": 3580000, "exceeds_limit": false, "shortfall": 0, "allocations": [], "warnings": [] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": [], "description": "`[{product_id, qty}]`" }, "payment_plan": { "type": "object", "description": "`{method: LOAN | WALLET | SPLIT, wallet_amount?}`" }, "allocations": { "type": "array", "items": [], "description": "Member split, to validate it." } }, "required": [ "lines" ] }, "example": { "lines": [ { "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "qty": 10 }, { "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "qty": 2 } ], "payment_plan": { "method": "LOAN" } } } } } } }, "/members": { "get": { "tags": [ "Cart, members and consent" ], "summary": "Members of the group", "description": "Members of the group. `id` is the app's own member id (`memberID`). Phones are masked.", "operationId": "get_members", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "101", "name": "Mary Akello", "member_number": 101, "phone": "+256 7•• ••• 101", "has_phone": true, "active": true, "officer_role": "CHAIRPERSON", "eligible": true, "ineligible_reason": null }, { "id": "102", "name": "Grace Nakato", "member_number": 102, "phone": "+256 7•• ••• 102", "has_phone": true, "active": true, "officer_role": "TREASURER", "eligible": true, "ineligible_reason": null } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/allocations/suggest": { "post": { "tags": [ "Cart, members and consent" ], "summary": "Proposes how to split each line between members", "description": "Proposes how to split each line between members. `subject_hash` is what that member's consent must cover.", "operationId": "post_orders_allocations_suggest", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "mode": "EVEN", "allocations": [ { "member_id": "101", "lines": [ { "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "qty": 4 }, { "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "qty": 1 } ], "amount": 605000, "subject_hash": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87:4|a32964e9-d0f9-4681-9fae-c08e97079f31:1" }, { "member_id": "102", "lines": [ { "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "qty": 3 }, { "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "qty": 1 } ], "amount": 500000, "subject_hash": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87:3|a32964e9-d0f9-4681-9fae-c08e97079f31:1" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": [], "description": "`[{product_id, qty}]`" }, "member_ids": { "type": "array", "items": [], "description": "Members receiving inputs." } }, "required": [ "lines", "member_ids" ] }, "example": { "lines": [ { "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "qty": 10 }, { "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "qty": 2 } ], "member_ids": [ "101", "102" ] } } } } } }, "/members/{id}/consent-options": { "get": { "tags": [ "Cart, members and consent" ], "summary": "How this member can consent to an amount: own phone, a shared phone, or witnessed by an Agent or officer, each with its ", "description": "How this member can consent to an amount: own phone, a shared phone, or witnessed by an Agent or officer, each with its cap and whether it is available.", "operationId": "get_members_id_consent_options", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "amount", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The member's share in currency units." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "member_id": "105", "amount": 50000, "options": [ { "method": "OWN_PHONE", "assurance": "HIGH", "available": false, "cap": null, "remaining_cap": null, "masked_phone": null, "reason": "NO_PHONE" }, { "method": "SHARED_PHONE", "assurance": "MEDIUM", "available": false, "cap": 1000000, "remaining_cap": 950000, "phones": [], "reason": "NO_SHARED_PHONE" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/consents/challenge": { "post": { "tags": [ "Cart, members and consent" ], "summary": "Sends a code to the member's phone for their share", "description": "Sends a code to the member's phone for their share. Use `purpose: PLEDGE` with `subject_type: LISTING` and `qty_kg` for harvest pledges.", "operationId": "post_consents_challenge", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "challenge_id": "a32964e9-f0b8-44df-838b-e511d80314c8", "masked_phone": "+256 7•• ••• 101", "summary_text": "4 kg Maize seed (Longe 5), 1 bag DAP fertiliser 50 kg worth 605,000", "subject_hash": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87:4|a32964e9-d0f9-4681-9fae-c08e97079f31:1", "method": "OWN_PHONE", "expires_at": "2026-11-06T16:27:00Z", "id": "a32964e9-f0b8-44df-838b-e511d80314c8", "amount": 605000 } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "member_id": { "type": "string", "description": "Member id." }, "purpose": { "type": "string", "description": "`ALLOCATION` (default) or `PLEDGE`." }, "subject_type": { "type": "string", "description": "`ORDER_DRAFT` or `LISTING`." }, "subject_id": { "type": "string", "description": "The draft's Idempotency-Key, or the listing id." }, "allocation": { "type": "array", "items": [], "description": "`[{product_id, qty}]` for ALLOCATION." }, "qty_kg": { "type": "number", "description": "For PLEDGE." } }, "required": [ "member_id", "subject_id" ] }, "example": { "member_id": "101", "purpose": "ALLOCATION", "subject_type": "ORDER_DRAFT", "subject_id": "4f721602-eb57-4df4-b091-b109d738b071", "allocation": [ { "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "qty": 4 }, { "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "qty": 1 } ] } } } } } }, "/consents/verify": { "post": { "tags": [ "Cart, members and consent" ], "summary": "Checks the member's code and records the consent.", "description": "Checks the member's code and records the consent.", "operationId": "post_consents_verify", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "consent_id": "a32964e9-f315-4748-aa61-90312df8186f", "member_id": "101", "subject_hash": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87:4|a32964e9-d0f9-4681-9fae-c08e97079f31:1", "method": "OWN_PHONE", "assurance": "HIGH", "status": "VERIFIED" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "format": "uuid", "description": "" }, "otp": { "type": "string", "description": "The code the member received." } }, "required": [ "challenge_id", "otp" ] }, "example": { "challenge_id": "a32964e9-f0b8-44df-838b-e511d80314c8", "otp": "235832" } } } } } }, "/consents/witnessed": { "post": { "tags": [ "Cart, members and consent" ], "summary": "Consent for a member with no phone, witnessed by the signed-in Agent with a signature and a photo", "description": "Consent for a member with no phone, witnessed by the signed-in Agent with a signature and a photo. Needs the Agent capability `witness.sign`. Capped by `config.consent.witnessed_max_amount`.", "operationId": "post_consents_witnessed", "security": [ { "groupBasic": [], "agentAuthority": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "member_id": { "type": "string", "description": "" }, "subject_id": { "type": "string", "description": "Draft key." }, "allocation": { "type": "array", "items": [], "description": "" }, "signature_evidence_id": { "type": "string", "format": "uuid", "description": "Uploaded signature." }, "photo_evidence_id": { "type": "string", "format": "uuid", "description": "Uploaded member photo." }, "witness_user_ids": { "type": "array", "items": [], "description": "" } }, "required": [ "member_id", "subject_id", "allocation", "signature_evidence_id", "photo_evidence_id" ] } } } } } }, "/consents/{id}/withdraw": { "post": { "tags": [ "Cart, members and consent" ], "summary": "Withdraws a consent before the order is sent.", "description": "Withdraws a consent before the order is sent.", "operationId": "post_consents_id_withdraw", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/members/{id}/phones": { "post": { "tags": [ "Cart, members and consent" ], "summary": "Adds a phone for a member (own or shared) and sends it a code.", "description": "Adds a phone for a member (own or shared) and sends it a code.", "operationId": "post_members_id_phones", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "msisdn": { "type": "string", "description": "Phone number." }, "kind": { "type": "string", "description": "`OWN` or `SHARED`." }, "holder_name": { "type": "string", "description": "Who holds a shared phone." }, "relationship": { "type": "string", "description": "" } }, "required": [ "msisdn", "kind" ] } } } } } }, "/members/{id}/phones/verify": { "post": { "tags": [ "Cart, members and consent" ], "summary": "Confirms the new phone with its code, then checks the name on its mobile money account", "description": "Confirms the new phone with its code, then checks the name on its mobile money account. An `OWN` phone must be in the member's name; otherwise `422` with `details.registered_name`, and the app should offer to add it as a shared phone. A `SHARED` phone takes the holder's real name. Returns `holder_name`, `registered_name` and `name_checked`.", "operationId": "post_members_id_phones_verify", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "format": "uuid", "description": "" }, "otp": { "type": "string", "description": "" } }, "required": [ "challenge_id", "otp" ] } } } } } }, "/orders": { "post": { "tags": [ "Orders" ], "summary": "Sends the order", "description": "Sends the order. **Idempotency-Key is required** and must equal the draft key used for the consents. Every member share needs a consent.", "operationId": "post_orders", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "checkout_id": "bea0bdf3-1653-43b5-866f-55f7f3b494ae", "orders": [ { "id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "provider": { "id": "a32964e9-ce56-46db-bac9-00e337495b2c", "name": "Agro Supply" }, "provider_name": "Agro Supply", "total": 1420000, "status": { "fulfilment": "SUBMITTED", "payment": "NOT_DUE", "loan": "NONE" }, "app_status": "WAITING_FOR_SUPPLIER", "display_status": { "label": "Waiting for the supplier", "tone": "waiting" }, "next_action": null, "created_at": "2026-11-06T16:18:33Z", "checkout_id": "bea0bdf3-1653-43b5-866f-55f7f3b494ae", "payment_method": "LOAN", "wallet_amount": 0, "loan_amount": 1420000, "lines": [ { "id": "a32964e9-ff30-4959-8590-57d6173b88e2", "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_price": 105000, "qty_ordered": 10, "qty_confirmed": null, "qty_dispatched": 0, "qty_delivered": 0, "qty_received": 0, "qty_rejected": 0, "line_total": 1050000 }, { "id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_price": 185000, "qty_ordered": 2, "qty_confirmed": null, "qty_dispatched": 0, "qty_delivered": 0, "qty_received": 0, "qty_rejected": 0, "line_total": 370000 } ], "delivery": { "use_group_location": true, "location_id": null, "hierarchy": { "region": "Central", "district": "Mukono", "subcounty": "Goma", "parish": "Seeta", "village": "Bajjo" }, "geo": { "lat": 0.3601, "lng": 32.7514 }, "landmark": "Near the church", "address": null, "preferred_window": "Next week", "receiver": { "name": "Mary Akello", "phone": "+256772000101" } }, "offer_expires_at": null, "timeline": [ { "status": "SUBMITTED", "event": "SUBMITTED", "at": "2026-11-06T16:18:33Z", "on_behalf_of_agent": null } ], "dispatches": [], "on_behalf_of_agent": null, "loan": null, "close_reason": null, "note": null } ], "reference": "IM-2026-000001", "total": 1420000 } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": [], "description": "`[{product_id, qty}]`" }, "allocations": { "type": "array", "items": [], "description": "`[{member_id, lines:[{product_id, qty}]}]`" }, "delivery": { "type": "object", "description": "`{use_group_location, location_id?, landmark?, preferred_window?}`" }, "payment_plan": { "type": "object", "description": "`{method: LOAN | WALLET | SPLIT, wallet_amount?}`" } }, "required": [ "lines", "allocations", "delivery", "payment_plan" ] }, "example": { "lines": [ { "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "qty": 10 }, { "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "qty": 2 } ], "allocations": [ { "member_id": "101", "lines": [ { "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "qty": 4 }, { "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "qty": 1 } ] }, { "member_id": "102", "lines": [ { "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "qty": 3 }, { "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "qty": 1 } ] } ], "delivery": { "use_group_location": true, "landmark": "Near the church", "preferred_window": "Next week" }, "payment_plan": { "method": "LOAN" } } } } } }, "get": { "tags": [ "Orders" ], "summary": "The group's orders, paged.", "description": "The group's orders, paged.", "operationId": "get_orders", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`active`, `needs_action` or `done`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "provider": { "id": "a32964e9-ce56-46db-bac9-00e337495b2c", "name": "Agro Supply" }, "provider_name": "Agro Supply", "total": 1420000, "status": { "fulfilment": "SUBMITTED", "payment": "NOT_DUE", "loan": "NONE" }, "app_status": "WAITING_FOR_SUPPLIER", "display_status": { "label": "Waiting for the supplier", "tone": "waiting" }, "next_action": null, "created_at": "2026-11-06T16:18:33Z" } ], "meta": { "page": 1, "per_page": 20, "total": 1 } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "One order with lines, delivery, timeline, dispatches and, once delivered, its loan.", "description": "One order with lines, delivery, timeline, dispatches and, once delivered, its loan.", "operationId": "get_orders_id", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "provider": { "id": "a32964e9-ce56-46db-bac9-00e337495b2c", "name": "Agro Supply" }, "provider_name": "Agro Supply", "total": 1420000, "status": { "fulfilment": "CLOSED", "payment": "PAID", "loan": "ACTIVE" }, "app_status": "CLOSED", "display_status": { "label": "Completed", "tone": "done" }, "next_action": null, "created_at": "2026-11-06T16:18:33Z", "checkout_id": "bea0bdf3-1653-43b5-866f-55f7f3b494ae", "payment_method": "LOAN", "wallet_amount": 0, "loan_amount": 1420000, "lines": [ { "id": "a32964e9-ff30-4959-8590-57d6173b88e2", "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_price": 105000, "qty_ordered": 10, "qty_confirmed": 10, "qty_dispatched": 10, "qty_delivered": 10, "qty_received": 10, "qty_rejected": 0, "line_total": 1050000 }, { "id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_price": 185000, "qty_ordered": 2, "qty_confirmed": 2, "qty_dispatched": 2, "qty_delivered": 2, "qty_received": 2, "qty_rejected": 0, "line_total": 370000 } ], "delivery": { "use_group_location": true, "location_id": null, "hierarchy": { "region": "Central", "district": "Mukono", "subcounty": "Goma", "parish": "Seeta", "village": "Bajjo" }, "geo": { "lat": 0.3601, "lng": 32.7514 }, "landmark": "Near the church", "address": null, "preferred_window": "Next week", "receiver": { "name": "Mary Akello", "phone": "+256772000101" } }, "offer_expires_at": "2026-11-09T16:18:33Z", "timeline": [ { "status": "SUBMITTED", "event": "SUBMITTED", "at": "2026-11-06T16:18:33Z", "on_behalf_of_agent": null }, { "status": "PROVIDER_REVIEW", "event": "PROVIDER_REVIEW", "at": "2026-11-06T16:18:33Z", "on_behalf_of_agent": null } ], "dispatches": [ { "id": "a32964ea-3019-489d-a64c-96ff8c9182e2", "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "qty": 10 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "qty": 2 } ], "carrier": { "name": "Driver", "phone": "+256700000000", "vehicle": "UAX 123B" }, "dispatched_at": "2026-11-06T16:19:35Z", "eta_from": null, "eta_to": null, "notes": null } ], "on_behalf_of_agent": null, "loan": { "id": "a32964ea-4fe5-4e07-b333-4756b3abda9f", "order_id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "order_ref": "IM-2026-000001", "provider_name": "Agro Supply", "principal": 1420000, "total_payable": 1420000, "repaid": 0, "outstanding": 1420000, "status": "ACTIVE", "activated_at": "2026-11-06T16:19:35Z", "due_date": "2027-04-06", "repayment_mode": "MONTHLY_INSTALMENTS", "interest_rate_pct": 0, "schedule": [ { "due_date": "2026-12-06", "amount": 284000, "paid": 0, "status": "DUE" }, { "due_date": "2027-01-06", "amount": 284000, "paid": 0, "status": "DUE" } ], "next_due": { "due_date": "2026-12-06", "amount": 284000 } }, "close_reason": "COMPLETED", "note": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/allocations": { "get": { "tags": [ "Orders" ], "summary": "Who receives what in this order.", "description": "Who receives what in this order.", "operationId": "get_orders_id_allocations", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964e9-ff9b-4920-abb9-44c20cb0eef0", "member_id": "101", "name": "Mary Akello", "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "qty_requested": 4, "qty_confirmed": 4, "qty_received": null, "amount": 420000, "attributed_amount": null, "status": "REQUESTED", "consent_id": "a32964e9-f315-4748-aa61-90312df8186f", "plot_id": null }, { "id": "a32964e9-ffbc-402c-a777-878780305792", "member_id": "101", "name": "Mary Akello", "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "qty_requested": 1, "qty_confirmed": 1, "qty_received": null, "amount": 185000, "attributed_amount": null, "status": "REQUESTED", "consent_id": "a32964e9-f315-4748-aa61-90312df8186f", "plot_id": null } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/cancel": { "post": { "tags": [ "Orders" ], "summary": "Cancels before the supplier starts preparing.", "description": "Cancels before the supplier starts preparing.", "operationId": "post_orders_id_cancel", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "" } } } } } } } }, "/orders/{id}/offer": { "get": { "tags": [ "Loan offer and signing" ], "summary": "The offer to review: confirmed lines, wallet and loan amounts, lender, repayment schedule preview (including any loan th", "description": "The offer to review: confirmed lines, wallet and loan amounts, lender, repayment schedule preview (including any loan the group already repays), credit before and after, signatories and members receiving.", "operationId": "get_orders_id_offer", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "offer_id": "a32964ea-1140-4c26-afe9-fee9d73b823f", "order_id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "provider_name": "Agro Supply", "version": 1, "status": "PENDING", "expires_at": "2026-11-09T16:18:33Z", "expires_in_hours": 72, "order_summary": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_price": 105000, "qty_ordered": 10, "qty_confirmed": 10, "line_total": 1050000 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_price": 185000, "qty_ordered": 2, "qty_confirmed": 2, "line_total": 370000 } ], "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_price": 105000, "qty_ordered": 10, "qty_confirmed": 10, "line_total": 1050000 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_price": 185000, "qty_ordered": 2, "qty_confirmed": 2, "line_total": 370000 } ], "items_total": 1420000, "loan_amount_up_to": 1420000, "loan_amount": 1420000, "wallet_amount": 0, "payment_method": "LOAN", "lender_name": "Ensibuuko Finance", "funding_status": "APPROVED", "tenor_days": 150, "repayment_note": "Repay a fixed amount every month. If you already have a running loan, your next monthly repayment includes this Marketplace loan once it is disbursed. Selling your harvest does not change what you owe.", "terms": { "financing_profile_id": "a32964e9-ce19-4d56-ac2a-a90533261ff2", "tenor_days": 150, "grace_days": 0, "repayment_mode": "MONTHLY_INSTALMENTS", "instalments": 5, "instalment_amount": 284000, "first_due_date": "2026-12-06", "schedule_preview": [ { "due_date": "2026-12-06", "principal": 284000, "interest": 0, "amount": 284000 }, { "due_date": "2027-01-06", "principal": 284000, "interest": 0, "amount": 284000 } ], "combined_repayment_preview": { "existing_loan_instalment": 0, "marketplace_instalment": 284000, "total": 284000, "due_date": "2026-12-06", "breakdown": [ { "kind": "MARKETPLACE", "loan_id": null, "label": "Marketplace IM-2026-000001", "amount": 284000, "due_date": "2026-12-06" } ] }, "interest_rate_pct": 0, "plain_language": "Repay a fixed amount every month. If you already have a running loan, your next monthly repayment includes this Marketplace loan once it is disbursed. Selling your harvest does not change what you owe.", "text_blocks": [], "agreement_url": null }, "credit": { "before": 5000000, "after": 3580000 }, "credit_before": 5000000, "credit_after": 3580000, "required_signatures": 2, "signatures": { "required": 2, "collected": 0, "signed": [], "eligible_signers": [ "101", "102" ] }, "signatories": [ { "id": "101", "name": "Mary Akello", "role": "CHAIRPERSON", "phone": "+256 7•• ••• 101", "signed": false }, { "id": "102", "name": "Grace Nakato", "role": "TREASURER", "phone": "+256 7•• ••• 102", "signed": false } ], "members_receiving": [ { "member_id": "101", "name": "Mary Akello", "amount": 605000, "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "qty_requested": 4, "qty_confirmed": 4 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "qty_requested": 1, "qty_confirmed": 1 } ], "status": "REQUESTED", "consent_status": "CONSENTED" }, { "member_id": "102", "name": "Grace Nakato", "amount": 500000, "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "qty_requested": 3, "qty_confirmed": 3 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "qty_requested": 1, "qty_confirmed": 1 } ], "status": "REQUESTED", "consent_status": "CONSENTED" } ], "changes": [], "final_amount_note": "Final loan = delivered quantity × price." } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/offer/otp": { "post": { "tags": [ "Loan offer and signing" ], "summary": "Sends a code to one officer.", "description": "Sends a code to one officer.", "operationId": "post_orders_id_offer_otp", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "challenge_id": "a32964ea-1672-4de7-9026-08bd3038a316", "id": "a32964ea-1672-4de7-9026-08bd3038a316", "masked_phone": "+256 7•• ••• 101", "expires_at": "2026-11-06T16:28:33Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signatory_id": { "type": "string", "description": "Officer's member id." } }, "required": [ "signatory_id" ] }, "example": { "signatory_id": "101" } } } } } }, "/orders/{id}/offer/sign": { "post": { "tags": [ "Loan offer and signing" ], "summary": "One officer signs", "description": "One officer signs. When enough have signed, `status` becomes `ACCEPTED` and the supplier prepares the order.", "operationId": "post_orders_id_offer_sign", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "offer_id": "a32964ea-1140-4c26-afe9-fee9d73b823f", "order_id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "provider_name": "Agro Supply", "version": 1, "status": "ACCEPTED", "expires_at": "2026-11-09T16:18:33Z", "expires_in_hours": 72, "order_summary": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_price": 105000, "qty_ordered": 10, "qty_confirmed": 10, "line_total": 1050000 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_price": 185000, "qty_ordered": 2, "qty_confirmed": 2, "line_total": 370000 } ], "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_price": 105000, "qty_ordered": 10, "qty_confirmed": 10, "line_total": 1050000 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_price": 185000, "qty_ordered": 2, "qty_confirmed": 2, "line_total": 370000 } ], "items_total": 1420000, "loan_amount_up_to": 1420000, "loan_amount": 1420000, "wallet_amount": 0, "payment_method": "LOAN", "lender_name": "Ensibuuko Finance", "funding_status": "APPROVED", "tenor_days": 150, "repayment_note": "Repay a fixed amount every month. If you already have a running loan, your next monthly repayment includes this Marketplace loan once it is disbursed. Selling your harvest does not change what you owe.", "terms": { "financing_profile_id": "a32964e9-ce19-4d56-ac2a-a90533261ff2", "tenor_days": 150, "grace_days": 0, "repayment_mode": "MONTHLY_INSTALMENTS", "instalments": 5, "instalment_amount": 284000, "first_due_date": "2026-12-06", "schedule_preview": [ { "due_date": "2026-12-06", "principal": 284000, "interest": 0, "amount": 284000 }, { "due_date": "2027-01-06", "principal": 284000, "interest": 0, "amount": 284000 } ], "combined_repayment_preview": { "existing_loan_instalment": 0, "marketplace_instalment": 284000, "total": 284000, "due_date": "2026-12-06", "breakdown": [ { "kind": "MARKETPLACE", "loan_id": null, "label": "Marketplace IM-2026-000001", "amount": 284000, "due_date": "2026-12-06" } ] }, "interest_rate_pct": 0, "plain_language": "Repay a fixed amount every month. If you already have a running loan, your next monthly repayment includes this Marketplace loan once it is disbursed. Selling your harvest does not change what you owe.", "text_blocks": [], "agreement_url": null }, "credit": { "before": 5000000, "after": 3580000 }, "credit_before": 5000000, "credit_after": 3580000, "required_signatures": 2, "signatures": { "required": 2, "collected": 2, "signed": [ { "id": "101", "name": "Mary Akello", "role": "CHAIRPERSON", "at": "2026-11-06T16:19:04Z" }, { "id": "102", "name": "Grace Nakato", "role": "TREASURER", "at": "2026-11-06T16:19:35Z" } ], "eligible_signers": [ "101", "102" ] }, "signatories": [ { "id": "101", "name": "Mary Akello", "role": "CHAIRPERSON", "phone": "+256 7•• ••• 101", "signed": true }, { "id": "102", "name": "Grace Nakato", "role": "TREASURER", "phone": "+256 7•• ••• 102", "signed": true } ], "members_receiving": [ { "member_id": "101", "name": "Mary Akello", "amount": 605000, "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "qty_requested": 4, "qty_confirmed": 4 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "qty_requested": 1, "qty_confirmed": 1 } ], "status": "ACCEPTED", "consent_status": "CONSENTED" }, { "member_id": "102", "name": "Grace Nakato", "amount": 500000, "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "qty_requested": 3, "qty_confirmed": 3 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "qty_requested": 1, "qty_confirmed": 1 } ], "status": "ACCEPTED", "consent_status": "CONSENTED" } ], "changes": [], "final_amount_note": "Final loan = delivered quantity × price.", "order_status": "OFFER_ACCEPTED" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signatory_id": { "type": "string", "description": "" }, "challenge_id": { "type": "string", "format": "uuid", "description": "" }, "otp": { "type": "string", "description": "" }, "accepted_terms": { "type": "boolean", "description": "Must be true." } }, "required": [ "signatory_id", "challenge_id", "otp", "accepted_terms" ] }, "example": { "signatory_id": "102", "challenge_id": "a32964ea-1c66-4931-b2a2-5326cb90281c", "otp": "359449", "accepted_terms": true } } } } } }, "/orders/{id}/offer/decline": { "post": { "tags": [ "Loan offer and signing" ], "summary": "The group declines the offer", "description": "The group declines the offer. The order closes and the reserved credit is released.", "operationId": "post_orders_id_offer_decline", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "" } } } } } } } }, "/orders/{id}/dispatches": { "get": { "tags": [ "Delivery and photos" ], "summary": "What the supplier sent, with the carrier.", "description": "What the supplier sent, with the carrier.", "operationId": "get_orders_id_dispatches", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964ea-3019-489d-a64c-96ff8c9182e2", "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "qty": 10 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "qty": 2 } ], "carrier": { "name": "Driver", "phone": "+256700000000", "vehicle": "UAX 123B" }, "dispatched_at": "2026-11-06T16:19:35Z", "eta_from": null, "eta_to": null, "notes": null } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/delivery-confirmation/template": { "get": { "tags": [ "Delivery and photos" ], "summary": "The confirmation form: lines with quantities delivered, the photo policy and what is still missing, reasons for refusing", "description": "The confirmation form: lines with quantities delivered, the photo policy and what is still missing, reasons for refusing items, and officers who can confirm.", "operationId": "get_orders_id_delivery_confirmation_template", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "order_id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "status": "AWAITING_GROUP_CONFIRMATION", "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_price": 105000, "qty_confirmed": 10, "qty_dispatched": 10, "qty_delivered_by_provider": 10 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_price": 185000, "qty_confirmed": 2, "qty_dispatched": 2, "qty_delivered_by_provider": 2 } ], "require_otp": true, "confirm_roles": [ "OFFICER", "Agent" ], "evidence": { "policy": { "actor": "GROUP", "per_order_line": { "min": 1 }, "when_rejected_qty_gt_0": { "slot": "damage_closeup", "min": 1 }, "optional": [ "group_with_goods" ], "signature": true, "gps": true, "max_distance_m": 300 }, "legacy": { "photo": { "required": false, "max": 3 }, "signature": { "required": true }, "gps": { "required": false } }, "missing": [ { "slot": "line_photo", "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "min": 1, "have": 0 }, { "slot": "line_photo", "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "min": 1, "have": 0 } ] }, "exception_reasons": [ { "code": "SHORT", "label": "Short delivery" }, { "code": "DAMAGED", "label": "Damaged items" } ], "signatories": [ { "id": "101", "name": "Mary Akello", "role": "CHAIRPERSON", "phone": "+256 7•• ••• 101" }, { "id": "102", "name": "Grace Nakato", "role": "TREASURER", "phone": "+256 7•• ••• 102" } ], "final_amount_note": "Final loan = delivered quantity × price." } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/evidence/policy": { "get": { "tags": [ "Delivery and photos" ], "summary": "Photo rules for a checkpoint and what is still missing.", "description": "Photo rules for a checkpoint and what is still missing.", "operationId": "get_evidence_policy", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "checkpoint", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`RECEIPT`, `LOADED`, `DROPOFF`, `CHECKIN_*`, `WEIGHIN`." }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "The order, to list what is missing." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "checkpoint": "RECEIPT", "policy": { "actor": "GROUP", "per_order_line": { "min": 1 }, "when_rejected_qty_gt_0": { "slot": "damage_closeup", "min": 1 }, "optional": [ "group_with_goods" ], "signature": true, "gps": true, "max_distance_m": 300 }, "missing": [ { "slot": "signature", "min": 1, "have": 0 } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/evidence": { "post": { "tags": [ "Delivery and photos" ], "summary": "Uploads one photo as `multipart/form-data`", "description": "Uploads one photo as `multipart/form-data`. **Idempotency-Key is required.** For large files or poor networks use the resumable upload below.", "operationId": "post_evidence", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-3c5c-46d4-a0ab-4f12a94461cc", "subject_type": "ORDER_RECEIPT", "subject_id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "slot_code": "line_photo", "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "status": "VALID", "flags": [], "sha256": "6962d86a401f90a7574aebbe6706bedd766e22202a3a0e2290eb58afc26f883e", "captured_at": "2026-11-06T16:19:35Z", "received_at": "2026-11-06T16:19:35Z", "gps": { "lat": 0.3601, "lng": 32.7514 }, "url": "/storage/inputmarket/GROUP/g-100/2026/11/4f46827f-3e21-47be-9982-ed4ac8e8cba4.jpg", "supersedes_id": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "JPEG photo." }, "subject_type": { "type": "string", "description": "`ORDER_RECEIPT` for the group." }, "subject_id": { "type": "string", "format": "uuid", "description": "Order id." }, "slot_code": { "type": "string", "description": "`line_photo`, `damage_closeup`, `signature`, `group_with_goods`." }, "order_line_id": { "type": "string", "format": "uuid", "description": "For per-line photos." }, "captured_at": { "type": "string", "format": "date-time", "description": "When the photo was taken." }, "gps": { "type": "object", "description": "`{lat, lng}`" }, "captured_offline": { "type": "boolean", "description": "" }, "supersedes_id": { "type": "string", "format": "uuid", "description": "Replaces an earlier photo." } }, "required": [ "file", "subject_type", "subject_id", "slot_code", "captured_at" ] } } } } } }, "/uploads": { "post": { "tags": [ "Delivery and photos" ], "summary": "Starts a resumable upload", "description": "Starts a resumable upload. Send the same metadata as `/evidence` plus `size_bytes`. **Idempotency-Key is required.** Returns the upload id and `chunk_size`; the `Upload-Offset` header starts at 0.", "operationId": "post_uploads", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/uploads/{id}": { "patch": { "tags": [ "Delivery and photos" ], "summary": "Sends the next chunk as the raw request body, with header `Upload-Offset` set to the bytes already sent", "description": "Sends the next chunk as the raw request body, with header `Upload-Offset` set to the bytes already sent. Replies `204` with the new `Upload-Offset`.", "operationId": "patch_uploads_id", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Delivery and photos" ], "summary": "Where an upload stands after a lost connection: headers `Upload-Offset`, `Upload-Length`, `Upload-Status`.", "description": "Where an upload stands after a lost connection: headers `Upload-Offset`, `Upload-Length`, `Upload-Status`.", "operationId": "get_uploads_id", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/uploads/{id}/complete": { "post": { "tags": [ "Delivery and photos" ], "summary": "Finishes the upload and returns the same evidence object as `POST /evidence`.", "description": "Finishes the upload and returns the same evidence object as `POST /evidence`.", "operationId": "post_uploads_id_complete", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/delivery-confirmation/otp": { "post": { "tags": [ "Delivery and photos" ], "summary": "Sends a code to the officer confirming.", "description": "Sends a code to the officer confirming.", "operationId": "post_orders_id_delivery_confirmation_otp", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "challenge_id": "a32964ea-4324-4586-934f-d6aa794defe1", "id": "a32964ea-4324-4586-934f-d6aa794defe1", "masked_phone": "+256 7•• ••• 101", "expires_at": "2026-11-06T16:29:35Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "officer_id": { "type": "string", "description": "" } }, "required": [ "officer_id" ] }, "example": { "officer_id": "101" } } } } } }, "/orders/{id}/delivery-confirmations": { "post": { "tags": [ "Delivery and photos" ], "summary": "Confirms delivery", "description": "Confirms delivery. **Idempotency-Key is required.** Quantities refused need a `reason_code` and a damage photo. Refusing everything opens a dispute instead.", "operationId": "post_orders_id_delivery_confirmations", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "confirmation_id": "a32964ea-45e2-48a9-9b59-3f4d76c0206d", "status": "CONFIRMED", "order_status": "CLOSED", "payment_status": "PAID", "final_amount": 1420000, "wallet_applied": 0, "loan_amount": 1420000, "next_steps": "Thank you. The supplier will now be paid and your loan will start." } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": [], "description": "`[{order_line_id, qty_received, qty_rejected, reason_code?}]`" }, "photo_ids": { "type": "array", "items": [], "description": "Evidence ids." }, "signature_id": { "type": "string", "format": "uuid", "description": "" }, "gps": { "type": "object", "description": "`{lat, lng}`" }, "receiver": { "type": "object", "description": "`{name, phone, phone_token}`. `phone_token` from phone checks, unless the phone is the confirming officer's." }, "challenge_id": { "type": "string", "description": "The officer's code." }, "otp": { "type": "string", "description": "The officer's code." }, "exception_reason_code": { "type": "string", "description": "" }, "notes": { "type": "string", "description": "" } }, "required": [ "lines", "photo_ids", "signature_id", "gps", "challenge_id", "otp" ] }, "example": { "receiver": { "name": "Mary Akello", "phone": "+256772000101" }, "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "qty_received": 10, "qty_rejected": 0, "reason_code": null }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "qty_received": 2, "qty_rejected": 0, "reason_code": null } ], "photo_ids": [ "a32964ea-3c5c-46d4-a0ab-4f12a94461cc", "a32964ea-3eb2-4a9a-bdc8-6a651680c12b" ], "signature_id": "a32964ea-4103-47eb-9807-0637be57af72", "gps": { "lat": 0.3601, "lng": 32.7514 }, "challenge_id": "a32964ea-4324-4586-934f-d6aa794defe1", "otp": "321259" } } } } } }, "/orders/{id}/disputes": { "post": { "tags": [ "Delivery and photos" ], "summary": "Reports a problem with an order", "description": "Reports a problem with an order. Ensibuuko reviews it; payment to the supplier waits.", "operationId": "post_orders_id_disputes", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason_code": { "type": "string", "description": "One of `config.dispute_reasons`." }, "notes": { "type": "string", "description": "" }, "evidence_ids": { "type": "array", "items": [], "description": "" } }, "required": [ "reason_code" ] } } } } }, "get": { "tags": [ "Delivery and photos" ], "summary": "Disputes on an order.", "description": "Disputes on an order.", "operationId": "get_orders_id_disputes", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/evidence": { "get": { "tags": [ "Delivery and photos" ], "summary": "Photos recorded on an order.", "description": "Photos recorded on an order.", "operationId": "get_orders_id_evidence", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/loans": { "get": { "tags": [ "Loans and repayments" ], "summary": "The group's Marketplace loans, paged.", "description": "The group's Marketplace loans, paged.", "operationId": "get_loans", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964ea-4fe5-4e07-b333-4756b3abda9f", "order_id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "order_ref": "IM-2026-000001", "provider_name": "Agro Supply", "principal": 1420000, "total_payable": 1420000, "repaid": 0, "outstanding": 1420000, "status": "ACTIVE", "activated_at": "2026-11-06T16:19:35Z", "due_date": "2027-04-06", "repayment_mode": "MONTHLY_INSTALMENTS", "interest_rate_pct": 0, "schedule": [ { "due_date": "2026-12-06", "amount": 284000, "paid": 0, "status": "DUE" }, { "due_date": "2027-01-06", "amount": 284000, "paid": 0, "status": "DUE" } ], "next_due": { "due_date": "2026-12-06", "amount": 284000 } } ], "meta": { "page": 1, "per_page": 20, "total": 1 } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/loans/{id}": { "get": { "tags": [ "Loans and repayments" ], "summary": "One loan with its schedule.", "description": "One loan with its schedule.", "operationId": "get_loans_id", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-4fe5-4e07-b333-4756b3abda9f", "order_id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "order_ref": "IM-2026-000001", "provider_name": "Agro Supply", "principal": 1420000, "total_payable": 1420000, "repaid": 0, "outstanding": 1420000, "status": "ACTIVE", "activated_at": "2026-11-06T16:19:35Z", "due_date": "2027-04-06", "repayment_mode": "MONTHLY_INSTALMENTS", "interest_rate_pct": 0, "schedule": [ { "due_date": "2026-12-06", "amount": 284000, "paid": 0, "status": "DUE" }, { "due_date": "2027-01-06", "amount": 284000, "paid": 0, "status": "DUE" } ], "next_due": { "due_date": "2026-12-06", "amount": 284000 } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/loans/{id}/repayments": { "get": { "tags": [ "Loans and repayments" ], "summary": "Repayments received: `[{id, amount, channel, reference, received_at}]`.", "description": "Repayments received: `[{id, amount, channel, reference, received_at}]`.", "operationId": "get_loans_id_repayments", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Loans and repayments" ], "summary": "Direct mobile-money repayment", "description": "Direct mobile-money repayment. **Off** until `features.direct_repayment` is true; groups repay through the normal Chomoka repayment flow.", "operationId": "post_loans_id_repayments", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "description": "" }, "msisdn": { "type": "string", "description": "" } }, "required": [ "amount", "msisdn" ] } } } } } }, "/repayments/next": { "get": { "tags": [ "Loans and repayments" ], "summary": "The next amount due across Marketplace loans and the group's other running loans, with a breakdown.", "description": "The next amount due across Marketplace loans and the group's other running loans, with a breakdown.", "operationId": "get_repayments_next", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "due_date": "2026-12-06", "total": 284000, "breakdown": [ { "kind": "MARKETPLACE", "loan_id": "a32964ea-4fe5-4e07-b333-4756b3abda9f", "label": "Marketplace IM-2026-000001", "amount": 284000, "due_date": "2026-12-06" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sync/snapshot": { "get": { "tags": [ "Offline sync" ], "summary": "Everything that changed since a time: orders, offers, loans, plots, listings, settlements, price proposals, notification", "description": "Everything that changed since a time: orders, offers, loans, plots, listings, settlements, price proposals, notifications, and `tombstones` for deleted items. Save `server_time` and send it as `since` next time.", "operationId": "get_sync_snapshot", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Last `server_time` you saved. Omit for a full snapshot." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "since": "1970-01-01T00:00:00Z", "server_time": "2026-11-06T16:19:35Z", "orders": [ { "id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "provider": { "id": "a32964e9-ce56-46db-bac9-00e337495b2c", "name": "Agro Supply" }, "provider_name": "Agro Supply", "total": 1420000, "status": { "fulfilment": "CLOSED", "payment": "PAID", "loan": "ACTIVE" }, "app_status": "CLOSED", "display_status": { "label": "Completed", "tone": "done" }, "next_action": null, "created_at": "2026-11-06T16:18:33Z" } ], "offers": [ { "id": "a32964ea-1140-4c26-afe9-fee9d73b823f", "order_id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "version": 1, "status": "ACCEPTED", "expires_at": "2026-11-09T16:18:33Z" } ], "loans": [ { "id": "a32964ea-4fe5-4e07-b333-4756b3abda9f", "order_id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "order_ref": "IM-2026-000001", "provider_name": "Agro Supply", "principal": 1420000, "total_payable": 1420000, "repaid": 0, "outstanding": 1420000, "status": "ACTIVE", "activated_at": "2026-11-06T16:19:35Z", "due_date": "2027-04-06", "repayment_mode": "MONTHLY_INSTALMENTS", "interest_rate_pct": 0, "schedule": [ { "due_date": "2026-12-06", "amount": 284000, "paid": 0, "status": "DUE" }, { "due_date": "2027-01-06", "amount": 284000, "paid": 0, "status": "DUE" } ], "next_due": { "due_date": "2026-12-06", "amount": 284000 } } ], "plots": [], "listings": [], "settlements": [], "price_proposals": [], "tombstones": [], "notifications": [ { "id": "a32964ea-20f7-4064-98f4-8af48c22b808", "type": "OFFER_ACCEPTED", "title": "Order confirmed", "body": "Order IM-2026-000001 is confirmed. The supplier will prepare it.", "payload": { "order_id": "a32964e9-fe70-4e98-9dde-56d03dd64881" }, "read_at": null, "created_at": "2026-11-06T16:19:35Z" }, { "id": "a32964ea-309e-4b2a-8bb5-b51d273e2975", "type": "ORDER_DISPATCHED", "title": "Your order is on the way", "body": "Order IM-2026-000001 is on the way.", "payload": { "order_id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "dispatch_id": "a32964ea-3019-489d-a64c-96ff8c9182e2" }, "read_at": null, "created_at": "2026-11-06T16:19:35Z" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/challenge": { "post": { "tags": [ "Agent sessions" ], "summary": "Starts sign-in", "description": "Starts sign-in. `identifier` is the Agent code or the Agent's phone.", "operationId": "post_agent_challenge", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "202": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "challenge_id": "a32964ea-5f80-4454-ad74-182a51cdf45e", "masked_phone": "+256 7•• ••• 001", "expires_at": "2026-11-06T16:29:35Z", "agent": { "id": "agent-1", "name": "Joan K." }, "id": "a32964ea-5f80-4454-ad74-182a51cdf45e" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Agent code or phone." } }, "required": [ "identifier" ] }, "example": { "identifier": "DCE-0001" } } } } } }, "/agent/verify": { "post": { "tags": [ "Agent sessions" ], "summary": "Returns the `authority_token` and what the Agent may do (`capabilities`).", "description": "Returns the `authority_token` and what the Agent may do (`capabilities`).", "operationId": "post_agent_verify", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "authority_token": "nzbOfZtKYJfJxTEp9QCdl1qsF8zDFW3mU5zFKTc9BVqM2mkNl4uD1mr104hhfyoJ", "authority_id": "a32964ea-6091-45ec-8753-01012c31be62", "expires_at": "2026-11-06T16:49:35Z", "agent": { "id": "agent-1", "name": "Joan K." }, "capabilities": [ "consent.collect", "witness.sign" ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "format": "uuid", "description": "" }, "otp": { "type": "string", "description": "" } }, "required": [ "challenge_id", "otp" ] }, "example": { "challenge_id": "a32964ea-5f80-4454-ad74-182a51cdf45e", "otp": "092396" } } } } } }, "/agent/session": { "delete": { "tags": [ "Agent sessions" ], "summary": "Ends the Agent session", "description": "Ends the Agent session. Accepted even after the token expired.", "operationId": "delete_agent_session", "security": [ { "groupBasic": [], "agentAuthority": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "204": { "description": "Example recorded from the test environment." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/seasons": { "get": { "tags": [ "Farm records" ], "summary": "Seasons.", "description": "Seasons.", "operationId": "get_seasons", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964ea-6866-481f-993f-4cab0149dc19", "name": "Season B 2026", "starts_on": "2026-10-06", "ends_on": "2027-04-06" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/farm/plots": { "get": { "tags": [ "Farm records" ], "summary": "Plots, optionally for one member.", "description": "Plots, optionally for one member.", "operationId": "get_farm_plots", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "member_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this member." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964ea-6ac0-4f16-8e08-0d63eaaf60ca", "member_id": "104", "name": "Main plot", "area_declared_acres": 2, "area_measured_acres": null, "measurement_method": null, "tenure": null, "geo_point": { "lat": 0.3601, "lng": 32.7514 }, "boundary": null, "gps_accuracy_m": null, "answers": [], "form_version": null, "status": "COMPLETE", "flags": [], "updated_at": "2026-11-06T16:19:35Z" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Farm records" ], "summary": "Adds a plot.", "description": "Adds a plot.", "operationId": "post_farm_plots", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-6ac0-4f16-8e08-0d63eaaf60ca", "member_id": "104", "name": "Main plot", "area_declared_acres": 2, "area_measured_acres": null, "measurement_method": null, "tenure": null, "geo_point": { "lat": 0.3601, "lng": 32.7514 }, "boundary": null, "gps_accuracy_m": null, "answers": [], "form_version": null, "status": "COMPLETE", "flags": [], "updated_at": "2026-11-06T16:19:35Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "member_id": { "type": "string", "description": "" }, "name": { "type": "string", "description": "" }, "area_declared_acres": { "type": "number", "description": "" }, "geo_point": { "type": "object", "description": "`{lat, lng}`" }, "tenure": { "type": "string", "description": "" }, "answers": { "type": "object", "description": "Form answers." } }, "required": [ "member_id", "name" ] }, "example": { "member_id": "104", "name": "Main plot", "area_declared_acres": 2, "geo_point": { "lat": 0.3601, "lng": 32.7514 } } } } } } }, "/farm/plots/{id}": { "put": { "tags": [ "Farm records" ], "summary": "Updates a plot.", "description": "Updates a plot.", "operationId": "put_farm_plots_id", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/farm/plots/{id}/boundary": { "post": { "tags": [ "Farm records" ], "summary": "Saves a walked boundary as a GeoJSON Polygon", "description": "Saves a walked boundary as a GeoJSON Polygon. Area is measured and compared with the declared area.", "operationId": "post_farm_plots_id_boundary", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "boundary": { "type": "object", "description": "Polygon." }, "gps_accuracy_m": { "type": "number", "description": "" } }, "required": [ "boundary" ] } } } } } }, "/farm/summary": { "get": { "tags": [ "Farm records" ], "summary": "How complete the group's farm records are.", "description": "How complete the group's farm records are.", "operationId": "get_farm_summary", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "completeness_pct": 16, "plots_count": 1, "complete_plots": 1, "flagged_plots": 0, "members_with_plots": 1, "members_total": 6, "total_declared_acres": 2, "total_measured_acres": 0, "expected_kg": 0, "season": { "id": "a32964ea-6866-481f-993f-4cab0149dc19", "name": "Season B 2026" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/farm/plots/{id}/seasons/{seasonId}": { "get": { "tags": [ "Farm records" ], "summary": "A plot's plan for a season (crop, variety, planting date, expected yield).", "description": "A plot's plan for a season (crop, variety, planting date, expected yield).", "operationId": "get_farm_plots_id_seasons_seasonid", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "seasonId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Farm records" ], "summary": "Saves that plan.", "description": "Saves that plan.", "operationId": "put_farm_plots_id_seasons_seasonid", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "seasonId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/farm/checkins/due": { "get": { "tags": [ "Farm records" ], "summary": "Field check-ins due.", "description": "Field check-ins due.", "operationId": "get_farm_checkins_due", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/farm/checkins": { "post": { "tags": [ "Farm records" ], "summary": "Submits a check-in with photos.", "description": "Submits a check-in with photos.", "operationId": "post_farm_checkins", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plot_season_id": { "type": "string", "format": "uuid", "description": "" }, "stage": { "type": "string", "description": "`PLANTING`, `GERMINATION`, `MIDSEASON`, `PREHARVEST`." }, "evidence_ids": { "type": "array", "items": [], "description": "" }, "agent_present": { "type": "boolean", "description": "" } }, "required": [ "plot_season_id", "stage" ] } } } } } }, "/forms/{key}": { "get": { "tags": [ "Farm records" ], "summary": "A dynamic form definition (questions for plots and seasons).", "description": "A dynamic form definition (questions for plots and seasons).", "operationId": "get_forms_key", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/forecast": { "get": { "tags": [ "Harvest sales (group side)" ], "summary": "Expected harvest from the farm records.", "description": "Expected harvest from the farm records.", "operationId": "get_offtake_forecast", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/listings": { "get": { "tags": [ "Harvest sales (group side)" ], "summary": "The group's listings.", "description": "The group's listings.", "operationId": "get_offtake_listings", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Harvest sales (group side)" ], "summary": "Creates a draft listing.", "description": "Creates a draft listing.", "operationId": "post_offtake_listings", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-6eb3-475f-ba5c-addc48e7cffb", "crop": "Maize", "season_id": "a32964ea-6866-481f-993f-4cab0149dc19", "qty_min_kg": 5000, "qty_max_kg": 9000, "pledged_kg": 0, "quality_spec": null, "ready_from": "2026-12-06", "ready_to": null, "pickup_location": null, "open_to": null, "linked_buyer_id": null, "status": "DRAFT" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "crop": { "type": "string", "description": "" }, "qty_min_kg": { "type": "number", "description": "" }, "qty_max_kg": { "type": "number", "description": "" }, "season_id": { "type": "string", "format": "uuid", "description": "" }, "ready_from": { "type": "string", "format": "date", "description": "" }, "ready_to": { "type": "string", "format": "date", "description": "" }, "quality_spec": { "type": "object", "description": "" }, "pickup_location": { "type": "object", "description": "" } }, "required": [ "crop", "qty_min_kg", "qty_max_kg" ] }, "example": { "crop": "Maize", "qty_min_kg": 5000, "qty_max_kg": 9000, "season_id": "a32964ea-6866-481f-993f-4cab0149dc19", "ready_from": "2026-12-06" } } } } } }, "/offtake/listings/{id}": { "put": { "tags": [ "Harvest sales (group side)" ], "summary": "Updates a draft listing.", "description": "Updates a draft listing.", "operationId": "put_offtake_listings_id", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/listings/{id}/publish": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "Shows the listing to offtakers.", "description": "Shows the listing to offtakers.", "operationId": "post_offtake_listings_id_publish", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-6eb3-475f-ba5c-addc48e7cffb", "crop": "Maize", "season_id": "a32964ea-6866-481f-993f-4cab0149dc19", "qty_min_kg": 5000, "qty_max_kg": 9000, "pledged_kg": 0, "quality_spec": null, "ready_from": "2026-12-06", "ready_to": null, "pickup_location": null, "open_to": "APPROVED_BUYERS", "linked_buyer_id": null, "status": "PUBLISHED" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/listings/{id}/pledges": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "A member pledges kilograms, with a PLEDGE consent.", "description": "A member pledges kilograms, with a PLEDGE consent.", "operationId": "post_offtake_listings_id_pledges", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964ea-7523-420d-8565-d4d695b5702c", "member_id": "104", "qty_kg": 4000, "consent_id": "a32964ea-7392-4f35-98c2-f4cf325474d7" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "member_id": { "type": "string", "description": "" }, "qty_kg": { "type": "number", "description": "" }, "consent_id": { "type": "string", "format": "uuid", "description": "From `/consents/verify`." } }, "required": [ "member_id", "qty_kg", "consent_id" ] }, "example": { "member_id": "104", "qty_kg": 4000, "consent_id": "a32964ea-7392-4f35-98c2-f4cf325474d7" } } } } } }, "/offtake/listings/{id}/offers": { "get": { "tags": [ "Harvest sales (group side)" ], "summary": "Offers from offtakers.", "description": "Offers from offtakers.", "operationId": "get_offtake_listings_id_offers", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964ea-77bd-4df0-ac6c-b0dcf0814fa9", "buyer": { "id": "a32964ea-6ce9-4e2a-ac8e-1b35f899c6c8", "name": "Grain Buyer Ltd" }, "version": 1, "qty_max_kg": 4000, "pickup_from": "2026-12-06", "pickup_to": null, "payment_terms_hours": 48, "quality_spec": null, "conditions": null, "expires_at": "2026-11-09T16:20:06Z", "status": "OPEN" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/offers/{id}/accept": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "Accepts an offer and creates a draft commitment", "description": "Accepts an offer and creates a draft commitment. Other open offers are declined.", "operationId": "post_offtake_offers_id_accept", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-7a8d-478f-983f-ac7c46b23737", "listing_id": "a32964ea-6eb3-475f-ba5c-addc48e7cffb", "buyer": { "id": "a32964ea-6ce9-4e2a-ac8e-1b35f899c6c8", "name": "Grain Buyer Ltd" }, "terms_version": 1, "terms": { "version": 1, "buyer": { "id": "a32964ea-6ce9-4e2a-ac8e-1b35f899c6c8", "name": "Grain Buyer Ltd" }, "crop": "Maize", "qty_kg": 4000, "tolerance_pct": 10, "pickup_from": "2026-12-06", "pickup_to": null, "payment_terms_hours": 48, "quality": null, "price": "Set by the buyer before pickup. The group accepts or declines it with an officer code.", "loans": "Selling the harvest does not change what the group owes on any loan.", "blocks": [ { "title": "What the group sells", "body": "Maize, about 4,000 kg (±10%)." }, { "title": "Payment", "body": "The buyer pays the group within 48 hours of the confirmed weigh-in." } ] }, "status": "DRAFT", "binding_at": null, "signatures": [] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/offers/{id}/decline": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "Declines an offer.", "description": "Declines an offer.", "operationId": "post_offtake_offers_id_decline", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/commitments/{id}": { "get": { "tags": [ "Harvest sales (group side)" ], "summary": "A commitment with its terms and signatures.", "description": "A commitment with its terms and signatures.", "operationId": "get_offtake_commitments_id", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-7a8d-478f-983f-ac7c46b23737", "listing_id": "a32964ea-6eb3-475f-ba5c-addc48e7cffb", "buyer": { "id": "a32964ea-6ce9-4e2a-ac8e-1b35f899c6c8", "name": "Grain Buyer Ltd" }, "terms_version": 1, "terms": { "version": 1, "buyer": { "id": "a32964ea-6ce9-4e2a-ac8e-1b35f899c6c8", "name": "Grain Buyer Ltd" }, "crop": "Maize", "qty_kg": 4000, "tolerance_pct": 10, "pickup_from": "2026-12-06", "pickup_to": null, "payment_terms_hours": 48, "quality": null, "price": "Set by the buyer before pickup. The group accepts or declines it with an officer code.", "loans": "Selling the harvest does not change what the group owes on any loan.", "blocks": [ { "title": "What the group sells", "body": "Maize, about 4,000 kg (±10%)." }, { "title": "Payment", "body": "The buyer pays the group within 48 hours of the confirmed weigh-in." } ] }, "status": "BINDING", "binding_at": "2026-11-06T16:20:06Z", "signatures": [ { "party": "GROUP_OFFICER", "signer_id": "101", "terms_version": 1, "signed_at": "2026-11-06T16:20:06Z", "current": true }, { "party": "GROUP_OFFICER", "signer_id": "102", "terms_version": 1, "signed_at": "2026-11-06T16:20:06Z", "current": true } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/commitments/{id}/otp": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "Sends a code to an officer.", "description": "Sends a code to an officer.", "operationId": "post_offtake_commitments_id_otp", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "challenge_id": "a32964ea-7c8b-4eb1-a465-6406812c5183", "masked_phone": "+256 7•• ••• 101", "expires_at": "2026-11-06T16:30:06Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "officer_id": { "type": "string", "description": "" } }, "required": [ "officer_id" ] }, "example": { "officer_id": "101" } } } } } }, "/offtake/commitments/{id}/sign": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "An officer signs with a code; an Agent signs as witness with only the agent header", "description": "An officer signs with a code; an Agent signs as witness with only the agent header. Binding once officers, the offtaker and the Agent (when required) have signed.", "operationId": "post_offtake_commitments_id_sign", "security": [ { "groupBasic": [] }, { "groupBasic": [], "agentAuthority": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-7a8d-478f-983f-ac7c46b23737", "listing_id": "a32964ea-6eb3-475f-ba5c-addc48e7cffb", "buyer": { "id": "a32964ea-6ce9-4e2a-ac8e-1b35f899c6c8", "name": "Grain Buyer Ltd" }, "terms_version": 1, "terms": { "version": 1, "buyer": { "id": "a32964ea-6ce9-4e2a-ac8e-1b35f899c6c8", "name": "Grain Buyer Ltd" }, "crop": "Maize", "qty_kg": 4000, "tolerance_pct": 10, "pickup_from": "2026-12-06", "pickup_to": null, "payment_terms_hours": 48, "quality": null, "price": "Set by the buyer before pickup. The group accepts or declines it with an officer code.", "loans": "Selling the harvest does not change what the group owes on any loan.", "blocks": [ { "title": "What the group sells", "body": "Maize, about 4,000 kg (±10%)." }, { "title": "Payment", "body": "The buyer pays the group within 48 hours of the confirmed weigh-in." } ] }, "status": "PARTIALLY_SIGNED", "binding_at": null, "signatures": [ { "party": "GROUP_OFFICER", "signer_id": "101", "terms_version": 1, "signed_at": "2026-11-06T16:20:06Z", "current": true } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "description": "Officer's code (not needed for the Agent witness)." }, "otp": { "type": "string", "description": "Officer's code (not needed for the Agent witness)." }, "terms_version": { "type": "integer", "description": "The version shown." } }, "required": [ "challenge_id", "otp", "terms_version" ] }, "example": { "challenge_id": "a32964ea-7c8b-4eb1-a465-6406812c5183", "otp": "228783", "terms_version": 1 } } } } } }, "/offtake/price-proposals": { "get": { "tags": [ "Harvest sales (group side)" ], "summary": "Prices offered by offtakers.", "description": "Prices offered by offtakers.", "operationId": "get_offtake_price_proposals", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964ea-8b75-4a07-b1c4-cf925e733ba7", "listing_id": "a32964ea-6eb3-475f-ba5c-addc48e7cffb", "commitment_id": "a32964ea-7a8d-478f-983f-ac7c46b23737", "buyer": { "id": "a32964ea-6ce9-4e2a-ac8e-1b35f899c6c8", "name": "Grain Buyer Ltd" }, "mode": "AT_OFFTAKE", "price_per_kg": 1200, "valid_until": "2026-11-07T16:20:06Z", "quality_terms": null, "status": "OPEN", "accepted_at": null } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/price-proposals/{id}/otp": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "Code for the officer accepting a price.", "description": "Code for the officer accepting a price.", "operationId": "post_offtake_price_proposals_id_otp", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "officer_id": { "type": "string", "description": "" } }, "required": [ "officer_id" ] } } } } } }, "/offtake/price-proposals/{id}/accept": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "Accepts the price.", "description": "Accepts the price.", "operationId": "post_offtake_price_proposals_id_accept", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-8b75-4a07-b1c4-cf925e733ba7", "listing_id": "a32964ea-6eb3-475f-ba5c-addc48e7cffb", "commitment_id": "a32964ea-7a8d-478f-983f-ac7c46b23737", "buyer": { "id": "a32964ea-6ce9-4e2a-ac8e-1b35f899c6c8", "name": "Grain Buyer Ltd" }, "mode": "AT_OFFTAKE", "price_per_kg": 1200, "valid_until": "2026-11-07T16:20:06Z", "quality_terms": null, "status": "ACCEPTED", "accepted_at": "2026-11-06T16:20:06Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "description": "" }, "otp": { "type": "string", "description": "" } }, "required": [ "challenge_id", "otp" ] }, "example": { "challenge_id": "a32964ea-8e0d-4613-92f3-6be86aa8c3fb", "otp": "621355" } } } } } }, "/offtake/price-proposals/{id}/decline": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "Declines the price.", "description": "Declines the price.", "operationId": "post_offtake_price_proposals_id_decline", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/pickups": { "get": { "tags": [ "Harvest sales (group side)" ], "summary": "Pickups booked by the offtaker.", "description": "Pickups booked by the offtaker.", "operationId": "get_offtake_pickups", "security": [ { "groupBasic": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964ea-9198-4943-ae3d-4c312c36ee67", "commitment_id": "a32964ea-7a8d-478f-983f-ac7c46b23737", "scheduled_at": "2026-11-07T16:20:06Z", "vehicle": "UBF 456K", "rep": { "name": "Peter", "phone": "+256772000777" }, "location": null, "ready_info": null, "status": "SCHEDULED" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/pickups/{id}/ready": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "The group says the harvest is ready.", "description": "The group says the harvest is ready.", "operationId": "post_offtake_pickups_id_ready", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "actual_qty_kg": { "type": "number", "description": "" }, "moisture_pct": { "type": "number", "description": "" }, "evidence_ids": { "type": "array", "items": [], "description": "" } } } } } } } }, "/offtake/weigh-ins/{id}": { "get": { "tags": [ "Harvest sales (group side)" ], "summary": "A weigh ticket.", "description": "A weigh ticket.", "operationId": "get_offtake_weigh_ins_id", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/weigh-ins/{id}/otp": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "Code for the officer confirming the weight.", "description": "Code for the officer confirming the weight.", "operationId": "post_offtake_weigh_ins_id_otp", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "officer_id": { "type": "string", "description": "" } }, "required": [ "officer_id" ] } } } } } }, "/offtake/weigh-ins/{id}/confirm": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "Confirms the weight", "description": "Confirms the weight. With a price accepted, the settlement is calculated (`settlement_id`).", "operationId": "post_offtake_weigh_ins_id_confirm", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-94c3-43d1-b208-3c79f828d8c7", "pickup_id": "a32964ea-9198-4943-ae3d-4c312c36ee67", "ticket_no": "T-1", "gross_kg": 4100, "tare_kg": 100, "net_kg": 4000, "moisture_pct": 12.5, "grade": "Grade 1", "deductions": [], "per_member": [ { "member_id": "104", "kg": 4000 } ], "evidence_ids": [], "confirmations": [ { "party": "BUYER_REP", "user_id": "a32964ea-6d0f-4efb-9d8a-d67fb46d93f2", "at": "2026-11-06T16:20:06Z", "otp": false }, { "party": "GROUP", "user_id": "102", "at": "2026-11-06T16:20:06Z", "otp": true } ], "status": "CONFIRMED", "supersedes_id": null, "settlement_id": "a32964ea-9a51-4d55-ad34-add04838b0b5" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "description": "" }, "otp": { "type": "string", "description": "" } }, "required": [ "challenge_id", "otp" ] }, "example": { "challenge_id": "a32964ea-97a4-4115-81e3-c205596d4c88", "otp": "273999" } } } } } }, "/offtake/weigh-ins/{id}/dispute": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "Disputes the weight; the offtaker must re-weigh.", "description": "Disputes the weight; the offtaker must re-weigh.", "operationId": "post_offtake_weigh_ins_id_dispute", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string", "description": "" } } } } } } } }, "/offtake/settlements/{id}": { "get": { "tags": [ "Harvest sales (group side)" ], "summary": "What the group is owed: net kg × price, deductions, each member's share.", "description": "What the group is owed: net kg × price, deductions, each member's share.", "operationId": "get_offtake_settlements_id", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-9a51-4d55-ad34-add04838b0b5", "weigh_in_id": "a32964ea-94c3-43d1-b208-3c79f828d8c7", "price_per_kg": 1200, "gross_value": 4800000, "other_deductions": [], "net_to_group": 4800000, "per_member": [ { "member_id": "104", "kg": 4000, "gross_share": 4800000, "net_share": 4800000 } ], "status": "COMPUTED", "balance_due_at": "2026-11-08T16:20:06Z", "paid_to_group_at": null, "payment_reference": null, "group_confirmed_at": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtake/settlements/{id}/confirm-received": { "post": { "tags": [ "Harvest sales (group side)" ], "summary": "The group confirms the money arrived", "description": "The group confirms the money arrived. The sale is complete.", "operationId": "post_offtake_settlements_id_confirm_received", "security": [ { "groupBasic": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-9a51-4d55-ad34-add04838b0b5", "weigh_in_id": "a32964ea-94c3-43d1-b208-3c79f828d8c7", "price_per_kg": 1200, "gross_value": 4800000, "other_deductions": [], "net_to_group": 4800000, "per_member": [ { "member_id": "104", "kg": 4000, "gross_share": 4800000, "net_share": 4800000 } ], "status": "GROUP_CONFIRMED", "balance_due_at": "2026-11-08T16:20:06Z", "paid_to_group_at": "2026-11-06T16:20:06Z", "payment_reference": "MM-123", "group_confirmed_at": "2026-11-06T16:20:06Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/provider/auth/otp": { "post": { "tags": [ "Supplier API" ], "summary": "Sends a sign-in code to a phone Ensibuuko registered for the company.", "description": "Sends a sign-in code to a phone Ensibuuko registered for the company.", "operationId": "post_provider_auth_otp", "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "202": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "challenge_id": "a32964ea-0919-46d4-bae4-417064ef2340", "masked_phone": "+256 7•• ••• 555", "expires_at": "2026-11-06T16:28:33Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International (+256…) or local form." }, "provider_id": { "type": "string", "format": "uuid", "description": "When one phone belongs to several companies." } }, "required": [ "phone" ] }, "example": { "phone": "+256772000555" } } } } } }, "/provider/auth/verify": { "post": { "tags": [ "Supplier API" ], "summary": "Returns a bearer token valid for 30 days", "description": "Returns a bearer token valid for 30 days. Send it as `Authorization: Bearer `.", "operationId": "post_provider_auth_verify", "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "token": "TEOLowo52zKgxoHv0hzDgoQDZqYNbpXvl1xyS8Ep0fcXPYu9Wu8nuG622ZUOyeb5", "expires_at": "2026-12-06T16:18:33Z", "user": { "id": "a32964ea-0881-4469-a852-6d7bea31ef6d", "name": "Sales desk", "role": "ADMIN" }, "provider": { "id": "a32964e9-ce56-46db-bac9-00e337495b2c", "name": "Agro Supply", "kind": "BOTH" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "format": "uuid", "description": "" }, "otp": { "type": "string", "description": "" } }, "required": [ "challenge_id", "otp" ] }, "example": { "challenge_id": "a32964ea-0919-46d4-bae4-417064ef2340", "otp": "607883" } } } } } }, "/provider/auth/logout": { "post": { "tags": [ "Supplier API" ], "summary": "Revokes the token.", "description": "Revokes the token.", "operationId": "post_provider_auth_logout", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/provider/orders": { "get": { "tags": [ "Supplier API" ], "summary": "Orders for the company, paged, with the group's delivery place and contacts.", "description": "Orders for the company, paged, with the group's delivery place and contacts.", "operationId": "get_provider_orders", "security": [ { "companyBearer": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "status": { "fulfilment": "SUBMITTED", "payment": "NOT_DUE" }, "group": { "id": "g-100" }, "delivery": { "use_group_location": true, "location_id": null, "hierarchy": { "region": "Central", "district": "Mukono", "subcounty": "Goma", "parish": "Seeta", "village": "Bajjo" }, "geo": { "lat": 0.3601, "lng": 32.7514 }, "landmark": "Near the church", "address": null, "preferred_window": "Next week", "receiver": { "name": "Mary Akello", "phone": "+256772000101" } }, "contacts": [ { "kind": "ACCOUNT_OWNER", "name": "Mary Akello", "role": "CHAIRPERSON", "phone": "+256772000101", "member_no": "101", "verified": true }, { "kind": "LOAN_CONTACT", "name": "Grace Nakato", "role": "TREASURER", "phone": "+256701000102", "member_no": "102", "verified": true } ], "lines": [ { "id": "a32964e9-ff30-4959-8590-57d6173b88e2", "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_provider_price": 100000, "qty_ordered": 10, "qty_confirmed": null, "qty_dispatched": 0, "qty_delivered": 0, "qty_received": 0, "qty_rejected": 0, "line_provider_total": 1000000 }, { "id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_provider_price": 180000, "qty_ordered": 2, "qty_confirmed": null, "qty_dispatched": 0, "qty_delivered": 0, "qty_received": 0, "qty_rejected": 0, "line_provider_total": 360000 } ], "provider_total": 1360000, "sla_due_at": "2026-11-07T16:18:33Z", "offer_expires_at": null, "dispatches": [], "deliveries": [], "payment": null, "created_at": "2026-11-06T16:18:33Z" } ], "meta": { "page": 1, "per_page": 20, "total": 1 } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/provider/orders/{id}": { "get": { "tags": [ "Supplier API" ], "summary": "One order", "description": "One order. Opening a new order marks it as being reviewed.", "operationId": "get_provider_orders_id", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "status": { "fulfilment": "PROVIDER_REVIEW", "payment": "NOT_DUE" }, "group": { "id": "g-100" }, "delivery": { "use_group_location": true, "location_id": null, "hierarchy": { "region": "Central", "district": "Mukono", "subcounty": "Goma", "parish": "Seeta", "village": "Bajjo" }, "geo": { "lat": 0.3601, "lng": 32.7514 }, "landmark": "Near the church", "address": null, "preferred_window": "Next week", "receiver": { "name": "Mary Akello", "phone": "+256772000101" } }, "contacts": [ { "kind": "ACCOUNT_OWNER", "name": "Mary Akello", "role": "CHAIRPERSON", "phone": "+256772000101", "member_no": "101", "verified": true }, { "kind": "LOAN_CONTACT", "name": "Grace Nakato", "role": "TREASURER", "phone": "+256701000102", "member_no": "102", "verified": true } ], "lines": [ { "id": "a32964e9-ff30-4959-8590-57d6173b88e2", "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_provider_price": 100000, "qty_ordered": 10, "qty_confirmed": null, "qty_dispatched": 0, "qty_delivered": 0, "qty_received": 0, "qty_rejected": 0, "line_provider_total": 1000000 }, { "id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_provider_price": 180000, "qty_ordered": 2, "qty_confirmed": null, "qty_dispatched": 0, "qty_delivered": 0, "qty_received": 0, "qty_rejected": 0, "line_provider_total": 360000 } ], "provider_total": 1360000, "sla_due_at": "2026-11-07T16:18:33Z", "offer_expires_at": null, "dispatches": [], "deliveries": [], "payment": null, "created_at": "2026-11-06T16:18:33Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/provider/orders/{id}/respond": { "post": { "tags": [ "Supplier API" ], "summary": "Answers a new order before `sla_due_at`.", "description": "Answers a new order before `sla_due_at`.", "operationId": "post_provider_orders_id_respond", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "status": { "fulfilment": "OFFER_READY", "payment": "NOT_DUE" }, "group": { "id": "g-100" }, "delivery": { "use_group_location": true, "location_id": null, "hierarchy": { "region": "Central", "district": "Mukono", "subcounty": "Goma", "parish": "Seeta", "village": "Bajjo" }, "geo": { "lat": 0.3601, "lng": 32.7514 }, "landmark": "Near the church", "address": null, "preferred_window": "Next week", "receiver": { "name": "Mary Akello", "phone": "+256772000101" } }, "contacts": [ { "kind": "ACCOUNT_OWNER", "name": "Mary Akello", "role": "CHAIRPERSON", "phone": "+256772000101", "member_no": "101", "verified": true }, { "kind": "LOAN_CONTACT", "name": "Grace Nakato", "role": "TREASURER", "phone": "+256701000102", "member_no": "102", "verified": true } ], "lines": [ { "id": "a32964e9-ff30-4959-8590-57d6173b88e2", "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_provider_price": 100000, "qty_ordered": 10, "qty_confirmed": 10, "qty_dispatched": 0, "qty_delivered": 0, "qty_received": 0, "qty_rejected": 0, "line_provider_total": 1000000 }, { "id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_provider_price": 180000, "qty_ordered": 2, "qty_confirmed": 2, "qty_dispatched": 0, "qty_delivered": 0, "qty_received": 0, "qty_rejected": 0, "line_provider_total": 360000 } ], "provider_total": 1360000, "sla_due_at": "2026-11-07T16:18:33Z", "offer_expires_at": "2026-11-09T16:18:33Z", "dispatches": [], "deliveries": [], "payment": null, "created_at": "2026-11-06T16:18:33Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "description": "`ACCEPT`, `PARTIAL` or `REJECT`." }, "lines": { "type": "array", "items": [], "description": "For PARTIAL: `[{order_line_id, qty_confirmed}]`." }, "reason": { "type": "string", "description": "Required for REJECT." } }, "required": [ "decision" ] }, "example": { "decision": "ACCEPT", "lines": [] } } } } } }, "/provider/orders/{id}/status": { "post": { "tags": [ "Supplier API" ], "summary": "Moves an order to `PREPARING`, or `CANCELLED` with a reason.", "description": "Moves an order to `PREPARING`, or `CANCELLED` with a reason.", "operationId": "post_provider_orders_id_status", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "status": { "fulfilment": "PREPARING", "payment": "NOT_DUE" }, "group": { "id": "g-100" }, "delivery": { "use_group_location": true, "location_id": null, "hierarchy": { "region": "Central", "district": "Mukono", "subcounty": "Goma", "parish": "Seeta", "village": "Bajjo" }, "geo": { "lat": 0.3601, "lng": 32.7514 }, "landmark": "Near the church", "address": null, "preferred_window": "Next week", "receiver": { "name": "Mary Akello", "phone": "+256772000101" } }, "contacts": [ { "kind": "ACCOUNT_OWNER", "name": "Mary Akello", "role": "CHAIRPERSON", "phone": "+256772000101", "member_no": "101", "verified": true }, { "kind": "LOAN_CONTACT", "name": "Grace Nakato", "role": "TREASURER", "phone": "+256701000102", "member_no": "102", "verified": true } ], "lines": [ { "id": "a32964e9-ff30-4959-8590-57d6173b88e2", "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_provider_price": 100000, "qty_ordered": 10, "qty_confirmed": 10, "qty_dispatched": 0, "qty_delivered": 0, "qty_received": 0, "qty_rejected": 0, "line_provider_total": 1000000 }, { "id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_provider_price": 180000, "qty_ordered": 2, "qty_confirmed": 2, "qty_dispatched": 0, "qty_delivered": 0, "qty_received": 0, "qty_rejected": 0, "line_provider_total": 360000 } ], "provider_total": 1360000, "sla_due_at": "2026-11-07T16:18:33Z", "offer_expires_at": "2026-11-09T16:18:33Z", "dispatches": [], "deliveries": [], "payment": null, "created_at": "2026-11-06T16:18:33Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`PREPARING` or `CANCELLED`." }, "reason": { "type": "string", "description": "" } }, "required": [ "status" ] }, "example": { "status": "PREPARING" } } } } } }, "/provider/evidence": { "post": { "tags": [ "Supplier API" ], "summary": "Uploads a loading or drop-off photo (multipart)", "description": "Uploads a loading or drop-off photo (multipart). Same fields as the group's `/evidence`, with `subject_type` `ORDER_LOADED` (slots `goods`, `vehicle_plate`) or `ORDER_DROPOFF` (slot `goods_at_site`, with GPS). Resumable uploads work the same under `/provider/uploads`.", "operationId": "post_provider_evidence", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-3328-4f87-9fef-4394725e4552", "subject_type": "ORDER_DROPOFF", "subject_id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "slot_code": "goods_at_site", "order_line_id": null, "status": "VALID", "flags": [], "sha256": "7876cba3c892d917245131be2e927c4989a45709e6cb7b58e5ac4f9d7f73203d", "captured_at": "2026-11-06T16:19:35Z", "received_at": "2026-11-06T16:19:35Z", "gps": { "lat": 0.3601, "lng": 32.7514 }, "url": "/storage/inputmarket/PROVIDER/a32964e9-ce56-46db-bac9-00e337495b2c/2026/11/88dd00cb-ab4b-4f7b-bac3-fa92277712f5.jpg", "supersedes_id": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/provider/orders/{id}/dispatches": { "post": { "tags": [ "Supplier API" ], "summary": "Records goods leaving", "description": "Records goods leaving. Needs the loading photos first. Without `lines`, everything confirmed is dispatched.", "operationId": "post_provider_orders_id_dispatches", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-3019-489d-a64c-96ff8c9182e2", "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "qty": 10 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "qty": 2 } ], "carrier": { "name": "Driver", "phone": "+256700000000", "vehicle": "UAX 123B" }, "dispatched_at": "2026-11-06T16:19:35Z", "eta_from": null, "eta_to": null, "notes": null, "order": { "id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "status": { "fulfilment": "DISPATCHED", "payment": "NOT_DUE" }, "group": { "id": "g-100" }, "delivery": { "use_group_location": true, "location_id": null, "hierarchy": { "region": "Central", "district": "Mukono", "subcounty": "Goma", "parish": "Seeta", "village": "Bajjo" }, "geo": { "lat": 0.3601, "lng": 32.7514 }, "landmark": "Near the church", "address": null, "preferred_window": "Next week", "receiver": { "name": "Mary Akello", "phone": "+256772000101" } }, "contacts": [ { "kind": "ACCOUNT_OWNER", "name": "Mary Akello", "role": "CHAIRPERSON", "phone": "+256772000101", "member_no": "101", "verified": true }, { "kind": "LOAN_CONTACT", "name": "Grace Nakato", "role": "TREASURER", "phone": "+256701000102", "member_no": "102", "verified": true } ], "lines": [ { "id": "a32964e9-ff30-4959-8590-57d6173b88e2", "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_provider_price": 100000, "qty_ordered": 10, "qty_confirmed": 10, "qty_dispatched": 10, "qty_delivered": 0, "qty_received": 0, "qty_rejected": 0, "line_provider_total": 1000000 }, { "id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_provider_price": 180000, "qty_ordered": 2, "qty_confirmed": 2, "qty_dispatched": 2, "qty_delivered": 0, "qty_received": 0, "qty_rejected": 0, "line_provider_total": 360000 } ], "provider_total": 1360000, "sla_due_at": "2026-11-07T16:18:33Z", "offer_expires_at": "2026-11-09T16:18:33Z", "dispatches": [ { "id": "a32964ea-3019-489d-a64c-96ff8c9182e2", "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "qty": 10 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "qty": 2 } ], "carrier": { "name": "Driver", "phone": "+256700000000", "vehicle": "UAX 123B" }, "dispatched_at": "2026-11-06T16:19:35Z", "eta_from": null, "eta_to": null, "notes": null } ], "deliveries": [], "payment": null, "created_at": "2026-11-06T16:18:33Z" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "carrier": { "type": "object", "description": "`{name, phone, phone_token, vehicle}`. A phone needs `phone_token` from `/provider/phone-checks`; the saved name is the confirmed one." }, "lines": { "type": "array", "items": [], "description": "`[{order_line_id, qty}]`" }, "eta_from": { "type": "string", "format": "date-time", "description": "" }, "eta_to": { "type": "string", "format": "date-time", "description": "" }, "notes": { "type": "string", "description": "" } }, "required": [ "carrier" ] }, "example": { "carrier": { "name": "Driver", "phone": "+256700000000", "vehicle": "UAX 123B" } } } } } } }, "/provider/orders/{id}/deliveries": { "post": { "tags": [ "Supplier API" ], "summary": "Records goods handed over", "description": "Records goods handed over. Needs the drop-off photo. The group then confirms in the app.", "operationId": "post_provider_orders_id_deliveries", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-3556-4312-a653-47054d8ad35b", "order": { "id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "reference": "IM-2026-000001", "status": { "fulfilment": "AWAITING_GROUP_CONFIRMATION", "payment": "NOT_DUE" }, "group": { "id": "g-100" }, "delivery": { "use_group_location": true, "location_id": null, "hierarchy": { "region": "Central", "district": "Mukono", "subcounty": "Goma", "parish": "Seeta", "village": "Bajjo" }, "geo": { "lat": 0.3601, "lng": 32.7514 }, "landmark": "Near the church", "address": null, "preferred_window": "Next week", "receiver": { "name": "Mary Akello", "phone": "+256772000101" } }, "contacts": [ { "kind": "ACCOUNT_OWNER", "name": "Mary Akello", "role": "CHAIRPERSON", "phone": "+256772000101", "member_no": "101", "verified": true }, { "kind": "LOAN_CONTACT", "name": "Grace Nakato", "role": "TREASURER", "phone": "+256701000102", "member_no": "102", "verified": true } ], "lines": [ { "id": "a32964e9-ff30-4959-8590-57d6173b88e2", "product_id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "name": "Maize seed (Longe 5)", "unit": "kg", "unit_provider_price": 100000, "qty_ordered": 10, "qty_confirmed": 10, "qty_dispatched": 10, "qty_delivered": 10, "qty_received": 0, "qty_rejected": 0, "line_provider_total": 1000000 }, { "id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "product_id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "name": "DAP fertiliser 50 kg", "unit": "bag", "unit_provider_price": 180000, "qty_ordered": 2, "qty_confirmed": 2, "qty_dispatched": 2, "qty_delivered": 2, "qty_received": 0, "qty_rejected": 0, "line_provider_total": 360000 } ], "provider_total": 1360000, "sla_due_at": "2026-11-07T16:18:33Z", "offer_expires_at": "2026-11-09T16:18:33Z", "dispatches": [ { "id": "a32964ea-3019-489d-a64c-96ff8c9182e2", "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "qty": 10 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "qty": 2 } ], "carrier": { "name": "Driver", "phone": "+256700000000", "vehicle": "UAX 123B" }, "dispatched_at": "2026-11-06T16:19:35Z", "eta_from": null, "eta_to": null, "notes": null } ], "deliveries": [ { "id": "a32964ea-3556-4312-a653-47054d8ad35b", "lines": [ { "order_line_id": "a32964e9-ff30-4959-8590-57d6173b88e2", "qty": 10 }, { "order_line_id": "a32964e9-ff5c-4d52-9fc6-fb189a78c321", "qty": 2 } ], "delivered_at": "2026-11-06T16:19:35Z", "delivered_to_name": "Mary" } ], "payment": null, "created_at": "2026-11-06T16:18:33Z" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "delivered_to_name": { "type": "string", "description": "" }, "lines": { "type": "array", "items": [], "description": "" }, "delivered_at": { "type": "string", "format": "date-time", "description": "" }, "gps": { "type": "object", "description": "" } } }, "example": { "delivered_to_name": "Mary" } } } } } }, "/provider/payments": { "get": { "tags": [ "Supplier API" ], "summary": "Payments to the company", "description": "Payments to the company. Reference ends in `-L` (lender part) or `-S` (Ensibuuko part).", "operationId": "get_provider_payments", "security": [ { "companyBearer": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964ea-48a0-498b-a9cc-c9c9c8f626ed", "order_id": "a32964e9-fe70-4e98-9dde-56d03dd64881", "order_reference": "IM-2026-000001", "amount": 1360000, "status": "PAID", "reference": "IMP-IM-2026-000001-L", "attempts": 1, "paid_at": "2026-11-06T16:19:35Z", "failure_reason": null } ], "meta": { "page": 1, "per_page": 20, "total": 1 } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/provider/settlements": { "get": { "tags": [ "Supplier API" ], "summary": "Settlement statements.", "description": "Settlement statements.", "operationId": "get_provider_settlements", "security": [ { "companyBearer": [] } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/provider/wallet": { "get": { "tags": [ "Supplier API" ], "summary": "The payout wallet: `balance` (null when the wallet service cannot be read), `currency`, withdrawal limits (`min`, `mobil", "description": "The payout wallet: `balance` (null when the wallet service cannot be read), `currency`, withdrawal limits (`min`, `mobile_money_max`, `bank_min`), `bank_mode` (`MANUAL` for now), `destinations` (the company admins' confirmed phones that mobile money can go to) and `open` (amount being withdrawn).", "operationId": "get_provider_wallet", "security": [ { "companyBearer": [] } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/provider/payouts": { "post": { "tags": [ "Supplier API" ], "summary": "Step 1 of a withdrawal", "description": "Step 1 of a withdrawal. Company admins only. Checks the amount against the limits and the live balance, then texts a code to the admin. Mobile money goes only to one of `destinations`. A bank withdrawal leaves the wallet at once and Ensibuuko pays the account by hand, usually within one working day; it is returned to the wallet if the transfer cannot be made.", "operationId": "post_provider_payouts", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "description": "`MOBILE_MONEY` or `BANK`." }, "amount": { "type": "integer", "description": "Whole currency units." }, "phone": { "type": "string", "description": "For MOBILE_MONEY: one of `destinations[].phone`." }, "bank_name": { "type": "string", "description": "For BANK." }, "account_name": { "type": "string", "description": "For BANK." }, "account_number": { "type": "string", "description": "For BANK." }, "branch": { "type": "string", "description": "For BANK." } }, "required": [ "method", "amount" ] } } } } }, "get": { "tags": [ "Supplier API" ], "summary": "Withdrawals, newest first, paged `{data, meta}`.", "description": "Withdrawals, newest first, paged `{data, meta}`.", "operationId": "get_provider_payouts", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/provider/payouts/confirm": { "post": { "tags": [ "Supplier API" ], "summary": "Step 2: the admin's code", "description": "Step 2: the admin's code. The money moves now. `status`: `PROCESSING` (mobile money on its way; becomes `PAID` or `FAILED`), `AWAITING_BANK` (Ensibuuko is paying the bank; becomes `PAID` with `bank_reference`, or `RETURNED` with `failure_reason`), or `FAILED` (nothing left the wallet). The admin gets a text when it finishes.", "operationId": "post_provider_payouts_confirm", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "format": "uuid", "description": "" }, "code": { "type": "string", "description": "" } }, "required": [ "challenge_id", "code" ] } } } } } }, "/provider/products": { "get": { "tags": [ "Supplier API" ], "summary": "The company's products with its own prices and stock.", "description": "The company's products with its own prices and stock.", "operationId": "get_provider_products", "security": [ { "companyBearer": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "name": "Maize seed (Longe 5)", "unit": "kg", "category_id": "a32964e9-cc8a-4c24-83fe-ea7c8267876f", "provider_unit_price": 100000, "availability": "IN_STOCK", "availability_mode": "UNLIMITED", "availability_flag": "IN_STOCK", "stock_qty": null, "min_qty": 1, "max_qty": 500, "qty_step": 1, "active": true, "pending_price_change": null }, { "id": "a32964e9-d0f9-4681-9fae-c08e97079f31", "name": "DAP fertiliser 50 kg", "unit": "bag", "category_id": "a32964e9-cde3-4bc5-8c92-111745620485", "provider_unit_price": 180000, "availability": "IN_STOCK", "availability_mode": "UNLIMITED", "availability_flag": "IN_STOCK", "stock_qty": null, "min_qty": 1, "max_qty": 100, "qty_step": 1, "active": true, "pending_price_change": null } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/provider/products/{id}": { "put": { "tags": [ "Supplier API" ], "summary": "Asks for a price change", "description": "Asks for a price change. Ensibuuko approves it before groups see it.", "operationId": "put_provider_products_id", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider_unit_price": { "type": "integer", "description": "New price per unit." } }, "required": [ "provider_unit_price" ] } } } } } }, "/provider/products/{id}/availability": { "put": { "tags": [ "Supplier API" ], "summary": "Updates stock.", "description": "Updates stock.", "operationId": "put_provider_products_id_availability", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964e9-cf34-4db6-a3d0-79e3a2eb5b87", "name": "Maize seed (Longe 5)", "unit": "kg", "category_id": "a32964e9-cc8a-4c24-83fe-ea7c8267876f", "provider_unit_price": 100000, "availability": "IN_STOCK", "availability_mode": "UNLIMITED", "availability_flag": "IN_STOCK", "stock_qty": 40, "min_qty": 1, "max_qty": 500, "qty_step": 1, "active": true, "pending_price_change": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "availability": { "type": "string", "description": "`IN_STOCK`, `LIMITED` or `OUT_OF_STOCK`." }, "stock_qty": { "type": "integer", "description": "" } }, "required": [ "availability" ] }, "example": { "availability": "LIMITED", "stock_qty": 40 } } } } } }, "/offtaker/listings": { "get": { "tags": [ "Offtaker API" ], "summary": "Harvest open to this offtaker in its country.", "description": "Harvest open to this offtaker in its country.", "operationId": "get_offtaker_listings", "security": [ { "companyBearer": [] } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtaker/listings/{id}": { "get": { "tags": [ "Offtaker API" ], "summary": "One listing", "description": "One listing. With `detail_level: COMMITTED` it adds the group, members and plot pins.", "operationId": "get_offtaker_listings_id", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtaker/listings/{id}/offers": { "post": { "tags": [ "Offtaker API" ], "summary": "Offers to buy.", "description": "Offers to buy.", "operationId": "post_offtaker_listings_id_offers", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-77bd-4df0-ac6c-b0dcf0814fa9", "listing_id": "a32964ea-6eb3-475f-ba5c-addc48e7cffb", "version": 1, "qty_max_kg": 4000, "pickup_from": "2026-12-06", "pickup_to": null, "payment_terms_hours": 48, "quality_spec": null, "conditions": null, "expires_at": "2026-11-09T16:20:06Z", "status": "OPEN" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "qty_max_kg": { "type": "number", "description": "" }, "pickup_from": { "type": "string", "format": "date", "description": "" }, "pickup_to": { "type": "string", "format": "date", "description": "" }, "payment_terms_hours": { "type": "integer", "description": "Pay within this many hours of the weigh-in." }, "quality_spec": { "type": "object", "description": "" }, "conditions": { "type": "string", "description": "" } }, "required": [ "qty_max_kg" ] }, "example": { "qty_max_kg": 4000, "payment_terms_hours": 48, "pickup_from": "2026-12-06" } } } } } }, "/offtaker/offers/{id}": { "put": { "tags": [ "Offtaker API" ], "summary": "Changes an open offer (a new version), or withdraws it.", "description": "Changes an open offer (a new version), or withdraws it.", "operationId": "put_offtaker_offers_id", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtaker/listings/{id}/price-proposals": { "post": { "tags": [ "Offtaker API" ], "summary": "Offers a price per kg", "description": "Offers a price per kg. The group accepts or declines; it cannot counter. One open price at a time.", "operationId": "post_offtaker_listings_id_price_proposals", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-8b75-4a07-b1c4-cf925e733ba7", "listing_id": "a32964ea-6eb3-475f-ba5c-addc48e7cffb", "commitment_id": "a32964ea-7a8d-478f-983f-ac7c46b23737", "mode": "AT_OFFTAKE", "price_per_kg": 1200, "valid_until": "2026-11-07T16:20:06Z", "quality_terms": null, "status": "OPEN" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "price_per_kg": { "type": "integer", "description": "" }, "valid_until": { "type": "string", "format": "date-time", "description": "Default 24 hours." }, "quality_terms": { "type": "object", "description": "" }, "pickup_id": { "type": "string", "format": "uuid", "description": "Price for one pickup only." } }, "required": [ "price_per_kg" ] }, "example": { "price_per_kg": 1200 } } } } } }, "/offtaker/price-proposals/{id}": { "put": { "tags": [ "Offtaker API" ], "summary": "Withdraws an open price.", "description": "Withdraws an open price.", "operationId": "put_offtaker_price_proposals_id", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtaker/commitments": { "get": { "tags": [ "Offtaker API" ], "summary": "The offtaker's commitments.", "description": "The offtaker's commitments.", "operationId": "get_offtaker_commitments", "security": [ { "companyBearer": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964ea-7a8d-478f-983f-ac7c46b23737", "listing_id": "a32964ea-6eb3-475f-ba5c-addc48e7cffb", "terms_version": 1, "terms": { "version": 1, "buyer": { "id": "a32964ea-6ce9-4e2a-ac8e-1b35f899c6c8", "name": "Grain Buyer Ltd" }, "crop": "Maize", "qty_kg": 4000, "tolerance_pct": 10, "pickup_from": "2026-12-06", "pickup_to": null, "payment_terms_hours": 48, "quality": null, "price": "Set by the buyer before pickup. The group accepts or declines it with an officer code.", "loans": "Selling the harvest does not change what the group owes on any loan.", "blocks": [ { "title": "What the group sells", "body": "Maize, about 4,000 kg (±10%)." }, { "title": "Payment", "body": "The buyer pays the group within 48 hours of the confirmed weigh-in." } ] }, "status": "FULFILLED", "binding_at": "2026-11-06T16:20:06Z", "signatures": [ { "party": "GROUP_OFFICER", "terms_version": 1, "signed_at": "2026-11-06T16:20:06Z" }, { "party": "GROUP_OFFICER", "terms_version": 1, "signed_at": "2026-11-06T16:20:06Z" } ] } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtaker/commitments/{id}/sign": { "post": { "tags": [ "Offtaker API" ], "summary": "Signs the commitment.", "description": "Signs the commitment.", "operationId": "post_offtaker_commitments_id_sign", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-7a8d-478f-983f-ac7c46b23737", "listing_id": "a32964ea-6eb3-475f-ba5c-addc48e7cffb", "terms_version": 1, "terms": { "version": 1, "buyer": { "id": "a32964ea-6ce9-4e2a-ac8e-1b35f899c6c8", "name": "Grain Buyer Ltd" }, "crop": "Maize", "qty_kg": 4000, "tolerance_pct": 10, "pickup_from": "2026-12-06", "pickup_to": null, "payment_terms_hours": 48, "quality": null, "price": "Set by the buyer before pickup. The group accepts or declines it with an officer code.", "loans": "Selling the harvest does not change what the group owes on any loan.", "blocks": [ { "title": "What the group sells", "body": "Maize, about 4,000 kg (±10%)." }, { "title": "Payment", "body": "The buyer pays the group within 48 hours of the confirmed weigh-in." } ] }, "status": "PARTIALLY_SIGNED", "binding_at": null, "signatures": [ { "party": "GROUP_OFFICER", "terms_version": 1, "signed_at": "2026-11-06T16:20:06Z" }, { "party": "GROUP_OFFICER", "terms_version": 1, "signed_at": "2026-11-06T16:20:06Z" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terms_version": { "type": "integer", "description": "The version you read." } }, "required": [ "terms_version" ] }, "example": { "terms_version": 1 } } } } } }, "/offtaker/pickups": { "post": { "tags": [ "Offtaker API" ], "summary": "Books a pickup on a binding commitment.", "description": "Books a pickup on a binding commitment.", "operationId": "post_offtaker_pickups", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-9198-4943-ae3d-4c312c36ee67", "status": "SCHEDULED", "scheduled_at": "2026-11-07T16:20:06Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "commitment_id": { "type": "string", "format": "uuid", "description": "" }, "scheduled_at": { "type": "string", "format": "date-time", "description": "" }, "vehicle": { "type": "string", "description": "" }, "rep": { "type": "object", "description": "`{name, phone, phone_token}`. A phone needs `phone_token` from `/offtaker/phone-checks`, unless it is a teammate's phone confirmed when they joined." }, "location": { "type": "object", "description": "" } }, "required": [ "commitment_id", "scheduled_at" ] }, "example": { "commitment_id": "a32964ea-7a8d-478f-983f-ac7c46b23737", "scheduled_at": "2026-11-07T16:20:06+00:00", "vehicle": "UBF 456K", "rep": { "name": "Peter", "phone": "+256772000777" } } } } } } }, "/offtaker/pickups/{id}/arrived": { "post": { "tags": [ "Offtaker API" ], "summary": "Marks arrival at the group.", "description": "Marks arrival at the group.", "operationId": "post_offtaker_pickups_id_arrived", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-9198-4943-ae3d-4c312c36ee67", "status": "ARRIVED" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtaker/weigh-ins": { "post": { "tags": [ "Offtaker API" ], "summary": "Records a weigh ticket", "description": "Records a weigh ticket. Net = gross − tare; members' shares follow their pledges unless `per_member` is given.", "operationId": "post_offtaker_weigh_ins", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "201": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-94c3-43d1-b208-3c79f828d8c7", "pickup_id": "a32964ea-9198-4943-ae3d-4c312c36ee67", "ticket_no": "T-1", "gross_kg": 4100, "tare_kg": 100, "net_kg": 4000, "moisture_pct": 12.5, "grade": "Grade 1", "deductions": [], "per_member": [ { "member_id": "104", "kg": 4000 } ], "confirmations": [], "status": "DRAFT", "supersedes_id": null, "settlement_id": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickup_id": { "type": "string", "format": "uuid", "description": "" }, "ticket_no": { "type": "string", "description": "" }, "gross_kg": { "type": "number", "description": "" }, "tare_kg": { "type": "number", "description": "" }, "moisture_pct": { "type": "number", "description": "" }, "grade": { "type": "string", "description": "" }, "deductions": { "type": "array", "items": [], "description": "`[{code, label, amount}]`, shown to the group." }, "per_member": { "type": "array", "items": [], "description": "`[{member_id, kg}]` adding up to net." }, "evidence_ids": { "type": "array", "items": [], "description": "" }, "supersedes_id": { "type": "string", "format": "uuid", "description": "Re-weigh of a disputed ticket." } }, "required": [ "pickup_id", "ticket_no", "gross_kg" ] }, "example": { "pickup_id": "a32964ea-9198-4943-ae3d-4c312c36ee67", "ticket_no": "T-1", "gross_kg": 4100, "tare_kg": 100, "moisture_pct": 12.5, "grade": "Grade 1" } } } } } }, "/offtaker/weigh-ins/{id}/confirm": { "post": { "tags": [ "Offtaker API" ], "summary": "The offtaker confirms its own ticket", "description": "The offtaker confirms its own ticket. The group confirms too.", "operationId": "post_offtaker_weigh_ins_id_confirm", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-94c3-43d1-b208-3c79f828d8c7", "pickup_id": "a32964ea-9198-4943-ae3d-4c312c36ee67", "ticket_no": "T-1", "gross_kg": 4100, "tare_kg": 100, "net_kg": 4000, "moisture_pct": 12.5, "grade": "Grade 1", "deductions": [], "per_member": [ { "member_id": "104", "kg": 4000 } ], "confirmations": [ { "party": "BUYER_REP", "user_id": "a32964ea-6d0f-4efb-9d8a-d67fb46d93f2", "at": "2026-11-06T16:20:06Z", "otp": false } ], "status": "DRAFT", "supersedes_id": null, "settlement_id": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtaker/settlements": { "get": { "tags": [ "Offtaker API" ], "summary": "What the offtaker owes each group.", "description": "What the offtaker owes each group.", "operationId": "get_offtaker_settlements", "security": [ { "companyBearer": [] } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "data": [ { "id": "a32964ea-9a51-4d55-ad34-add04838b0b5", "weigh_in_id": "a32964ea-94c3-43d1-b208-3c79f828d8c7", "price_per_kg": 1200, "gross_value": 4800000, "other_deductions": [], "net_to_group": 4800000, "status": "COMPUTED", "balance_due_at": "2026-11-08T16:20:06Z", "paid_to_group_at": null, "payment_reference": null } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtaker/settlements/{id}/pay-group": { "post": { "tags": [ "Offtaker API" ], "summary": "Records that the group was paid", "description": "Records that the group was paid. The group then confirms receipt.", "operationId": "post_offtaker_settlements_id_pay_group", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Example recorded from the test environment.", "content": { "application/json": { "example": { "id": "a32964ea-9a51-4d55-ad34-add04838b0b5", "weigh_in_id": "a32964ea-94c3-43d1-b208-3c79f828d8c7", "price_per_kg": 1200, "gross_value": 4800000, "other_deductions": [], "net_to_group": 4800000, "status": "BALANCE_PAID", "balance_due_at": "2026-11-08T16:20:06Z", "paid_to_group_at": "2026-11-06T16:20:06Z", "payment_reference": "MM-123" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "description": "Mobile-money or bank reference." } }, "required": [ "reference" ] }, "example": { "reference": "MM-123" } } } } } }, "/offtaker/fees": { "get": { "tags": [ "Offtaker API" ], "summary": "Fees the offtaker owes Ensibuuko per kg bought", "description": "Fees the offtaker owes Ensibuuko per kg bought. Never shown to or taken from groups.", "operationId": "get_offtaker_fees", "security": [ { "companyBearer": [] } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/offtaker/evidence": { "post": { "tags": [ "Offtaker API" ], "summary": "Uploads a weigh-in photo (multipart), slots `scale`, `loaded_truck`, `moisture_meter`.", "description": "Uploads a weigh-in photo (multipart), slots `scale`, `loaded_truck`, `moisture_meter`.", "operationId": "post_offtaker_evidence", "security": [ { "companyBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/payments": { "post": { "tags": [ "Payment results webhook" ], "summary": "Header `X-Inputmarket-Signature: sha256=` using the shared secret", "description": "Header `X-Inputmarket-Signature: sha256=` using the shared secret. A bad or missing signature returns `401`.", "operationId": "post_webhooks_payments", "security": [ { "webhookSignature": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A UUID per write; retries with the same key replay the first response." } ], "responses": { "200": { "description": "Success." }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "description": "The transfer reference the Marketplace sent (for example `IMP-IM-2026-000001-L`)." }, "status": { "type": "string", "description": "`SUCCESS`, `FAILED` or `PENDING`." }, "failure_reason": { "type": "string", "description": "" } }, "required": [ "reference", "status" ] } } } } } } }, "components": { "securitySchemes": { "groupBasic": { "type": "http", "scheme": "basic", "description": "Group key and secret, as the rest of the Chomoka app uses. Send X-Device-Id too." }, "agentAuthority": { "type": "apiKey", "in": "header", "name": "X-Agent-Authority", "description": "Token from POST /agent/verify, sent with the group header." }, "companyBearer": { "type": "http", "scheme": "bearer", "description": "Token from POST /provider/auth/verify. Lasts 30 days." }, "webhookSignature": { "type": "apiKey", "in": "header", "name": "X-Inputmarket-Signature", "description": "sha256= with the shared secret." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "UNAUTHENTICATED", "FORBIDDEN", "NOT_ELIGIBLE", "NOT_FOUND", "NOT_SUPPORTED", "VALIDATION_ERROR", "INVALID_STATE", "STALE_STATE", "DUPLICATE_REQUEST", "CREDIT_LIMIT_EXCEEDED", "PRODUCT_UNAVAILABLE", "PRICE_CHANGED", "OFFER_EXPIRED", "ALREADY_SIGNED", "OTP_INVALID", "OTP_EXPIRED", "OTP_LOCKED", "RATE_LIMITED", "WALLET_INSUFFICIENT", "PAYMENT_METHOD_NOT_ALLOWED", "EVIDENCE_REQUIRED", "EVIDENCE_EXPIRED", "HASH_MISMATCH", "INTEGRITY_FAILED", "ALLOCATION_MISMATCH", "MEMBER_INELIGIBLE", "CONSENT_REQUIRED", "CONSENT_CAP_EXCEEDED", "AGENT_ACTION_REQUIRES_LIVE", "FUNDING_UNAVAILABLE", "FUNDING_PENDING", "SERVER_ERROR" ] }, "message": { "type": "string" }, "details": [] } } } } } } }