{"openapi":"3.0.0","paths":{"/api/agent/destinations":{"get":{"operationId":"AgentCommerceController_destinations","summary":"Every destination deliverTo accepts, and every spelling of each","description":"The vocabulary is published rather than left to be brute-forced. Note that the bare two-letter code (\"LA\") is not the ISO 3166-2 code; the full form (\"NG-LA\") and the state name are accepted too.","parameters":[],"responses":{"200":{"description":""}},"tags":["agent-commerce"]}},"/api/agent/manifest":{"get":{"operationId":"AgentCommerceController_manifest","summary":"What this API is, what it can do, and how it expects to be used","description":"The entry point. Fetch this first: it names every endpoint, the payment model, the rate limits, and the fulfilment classes that appear on every listing. Stable and cacheable.","parameters":[],"responses":{"200":{"description":""}},"tags":["agent-commerce"]}},"/api/agent/search":{"get":{"operationId":"AgentCommerceController_search","summary":"Search the catalogue, optionally priced to a destination","description":"Natural-language search across Kiki merchants and indexed Nigerian marketplace listings. Pass `deliverTo` and each row carries a real courier quote and a landed cost, so one call is enough to compare on the number that matters. Every row states its fulfilment class: whether a human confirmation step stands between payment and dispatch.","parameters":[{"name":"q","required":false,"in":"query","description":"What to search for, in natural language. Omit to browse.","schema":{"example":"philips dry iron","type":"string"}},{"name":"deliverTo","required":false,"in":"query","description":"Destination Nigerian state — name, two-letter code, or ISO 3166-2 (\"Lagos\" / \"LA\" / \"NG-LA\"). See GET /agent/destinations. Supplying it turns every row into a landed cost — item plus real courier quote — which is the number an agent should actually compare on, and drops listings that cannot reach the destination at all.","schema":{"example":"LA","type":"string"}},{"name":"minPrice","required":false,"in":"query","description":"Minimum unit price, inclusive.","schema":{"type":"number"}},{"name":"maxPrice","required":false,"in":"query","description":"Maximum unit price, inclusive.","schema":{"type":"number"}},{"name":"instantOnly","required":false,"in":"query","description":"Only return listings that can be fulfilled without a human confirmation step — i.e. stock-tracked inventory from a merchant on Kiki.","schema":{"type":"string"}},{"name":"includeUndeliverable","required":false,"in":"query","description":"Include listings that do not record where they ship from. They cannot be delivered or collected, so a destination-scoped search drops them by default rather than letting an agent price something that can never arrive.","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","schema":{"enum":["relevance","price_asc","price_desc","newest"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Rows to return (max 50).","schema":{"default":20,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Offset for pagination.","schema":{"default":0,"type":"number"}}],"responses":{"200":{"description":""}},"tags":["agent-commerce"]}},"/api/agent/listings/{idOrSlug}":{"get":{"operationId":"AgentCommerceController_getListing","summary":"Inspect a single listing by UUID, slug, or URL","description":"Returns structured product specs, condition, stock/fulfilment class, variants, seller info, and optional courier landed cost when `deliverTo` is supplied.","parameters":[{"name":"idOrSlug","required":true,"in":"path","schema":{"type":"string"}},{"name":"deliverTo","required":false,"in":"query","description":"Optional destination Nigerian state — name, two-letter code, or ISO 3166-2 (\"Lagos\" / \"LA\" / \"NG-LA\"). Returns a live courier fee and landed cost.","schema":{"example":"LA","type":"string"}}],"responses":{"200":{"description":"Structured listing payload."},"404":{"description":"Listing not found or inactive."}},"tags":["agent-commerce"]}},"/api/agent/quote":{"post":{"operationId":"AgentCommerceController_quote","summary":"Authoritative price for a basket","description":"Live prices, a real courier fee for the exact pickup-to-destination route, and the per-line fulfilment class. Nothing is reserved. Baskets that cannot travel together are refused with the split the caller should make, rather than silently mispriced.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentQuoteDto"}}}},"responses":{"200":{"description":"Priced. NOTHING IS RESERVED — the body says so explicitly. This is a POST only because a basket does not fit in a query string; it is a read."},"400":{"description":"Basket spans more than one shipment. The body carries the exact split to make, as listing ids grouped per shipment."},"422":{"description":"A listing is unavailable, or its origin is unknown (permanent)."}},"tags":["agent-commerce"]}},"/api/agent/orders":{"post":{"operationId":"AgentCommerceController_createOrder","summary":"Create an order and get a payment URL for the buyer to authorise","description":"Re-validates the basket, writes the order unpaid, and opens a hosted payment page — bank transfer by default. The API never accepts card or account credentials: hand the returned URL to the person you are buying for. Pass `expectedTotal` to have the order refused rather than repriced if the number moved since you quoted.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentOrderDto"}}}},"responses":{"201":{"description":"Order created, unpaid. Returns trackingId, reference and a hosted payment URL for a PERSON to authorise. Replaying the same idempotencyKey returns this same order rather than creating another."},"400":{"description":"Invalid buyer, basket, destination, or missing idempotencyKey."},"422":{"description":"Price changed, or a listing went away."}},"tags":["agent-commerce"]}},"/api/agent/orders/{reference}":{"get":{"operationId":"AgentCommerceController_orderStatus","summary":"Order state and what to do next","description":"Accepts either identifier and they are interchangeable: the `reference` returned when the order was created, or the `trackingId` the buyer sees. Returns a normalised status plus an explicit `nextAction`, so an agent never has to infer intent from an internal status string. There is no webhook — poll this.","parameters":[{"name":"reference","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["agent-commerce"]}}},"info":{"title":"Kiki Commerce API","description":"Search, price and buy physical goods for delivery inside Nigeria. No key, no account, no session.","version":"1.0"},"tags":[{"name":"agent-commerce","description":"Machine-facing commerce API for autonomous shopping agents"}],"servers":[{"url":"https://api.xrnet.tech"}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"AgentLineDto":{"type":"object","properties":{"listingId":{"type":"string","description":"Listing id, as returned by /agent/search. Give exactly one of `listingId`, `slug` or `url`."},"slug":{"type":"string","description":"Product page slug — the last segment of kiki.com.ng/products/{slug}. Resolved to a listing id server-side.","example":"new-samsung-galaxy-s24-256-gb-gray-jgkuyeqe"},"url":{"type":"string","description":"Full product page URL, e.g. https://kiki.com.ng/products/{slug}. Resolved to a listing id server-side."},"quantity":{"type":"number","example":1,"minimum":1,"maximum":100}},"required":["quantity"]},"AgentQuoteDto":{"type":"object","properties":{"buyerEmail":{"type":"string","description":"Buyer email, used with buyerPhone to check first-order delivery eligibility."},"buyerPhone":{"type":"string","description":"Buyer phone, used with buyerEmail to check first-order delivery eligibility."},"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentLineDto"}},"deliverTo":{"type":"string","description":"Destination Nigerian state. Accepts the state name (\"Lagos\", \"Lagos State\"), the two-letter code (\"LA\") or the full ISO 3166-2 code (\"NG-LA\"). GET /agent/destinations lists every accepted spelling.","example":"LA"},"pickup":{"type":"boolean","description":"Set for pickup instead of delivery. Delivery is then zero.","default":false},"couponCode":{"type":"string","description":"Coupon code to apply."}},"required":["items","deliverTo"]},"AgentBuyerDto":{"type":"object","properties":{"firstname":{"type":"string","example":"Ada"},"lastname":{"type":"string","example":"Obi"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","description":"Nigerian phone number. The rider calls this on arrival.","example":"+2348012345678"},"address":{"type":"string","description":"Street address for delivery.","example":"12 Bode Thomas St"},"city":{"type":"string","example":"Surulere"},"state":{"type":"string","description":"Destination Nigerian state — name, two-letter code, or ISO 3166-2. Validated against GET /agent/destinations: this is the field a rider actually drives to, so it is checked at least as strictly as deliverTo.","example":"LA"},"country":{"type":"string","default":"Nigeria"}},"required":["firstname","lastname","email","phone","address","city","state"]},"AgentOrderDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentLineDto"}},"buyer":{"$ref":"#/components/schemas/AgentBuyerDto"},"pickup":{"type":"boolean","description":"Pickup instead of delivery.","default":false},"couponCode":{"type":"string","description":"Coupon code to apply."},"paymentChannel":{"type":"string","description":"Which rail the payment page should open on. `bank_transfer` is the default because it is what most Nigerian buyers actually use, and it is the one rail a person can complete from a banking app in seconds.","enum":["bank_transfer","ussd","card","online","pay_on_delivery"],"default":"bank_transfer"},"returnUrl":{"type":"string","description":"Where to send the buyer after the hosted payment page completes. Must be an https URL. Defaults to the Kiki order-tracking page."},"expectedTotal":{"type":"number","description":"Total the agent believes it is committing to, in major units. If the authoritative total differs by more than a naira the order is refused rather than silently repriced."},"idempotencyKey":{"type":"string","description":"Your own unique id for this purchase attempt. Replaying it returns the ORIGINAL order and payment URL instead of creating a second one. Without it there is no safe move when a request times out after the server has written the order: retrying may buy the item twice, and not retrying may abandon an order the buyer is about to be asked to pay for. There are no accounts here, so there is also no order list to reconcile against — send this on every order.","maxLength":128}},"required":["items","buyer","idempotencyKey"]}}}}