# Kibanda API

Kibanda runs a shop inside WhatsApp: customers browse, add to cart, pay (M-Pesa, card, or cash on delivery) and track their delivery without leaving the chat. The API connects that shop to everything else you run — Shopify, Odoo, Zoho, a POS, a spreadsheet, or an AI agent.

- **Products in.** Push your catalog and stock; customers see it on WhatsApp instantly.
- **Orders and customers out.** Every order, payment and delivery step is an event, delivered to your server as a signed webhook.
- **Checkout from anywhere.** Your website, an ad or an AI agent builds the cart; the customer confirms and pays in WhatsApp.
- **Agent-ready.** An MCP server for the shop owner's assistant, and one per shop for shoppers' assistants.
- **Reconcile with your ids.** Put your own id in `external_id` on products, customers and orders. You never have to store ours.

## Quickstart

**1. Get a key.** In the dashboard, open **Developers → API keys → Create key**. Test keys (`kb_test_…`) work on staging; live keys (`kb_live_…`) work in production.

```bash
export KIBANDA_KEY=kb_test_...
export KIBANDA_API=https://api-staging.kibanda.africa
```

**2. Add a product.** Money is always an integer in cents — `25000` is KES 250.

```bash
curl $KIBANDA_API/v1/products \
  -H "Authorization: Bearer $KIBANDA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Unga 2kg", "price": 25000, "stock": 40, "external_id": "SKU-1001"}'
```

It's on your WhatsApp menu now. The response includes a `code` like `UNG4`: anyone who sends "P-UNG4" to your number lands on that product.

**3. Get told about orders.**

```bash
curl $KIBANDA_API/v1/webhook_endpoints \
  -H "Authorization: Bearer $KIBANDA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/kibanda", "enabled_events": ["order.paid", "order.delivered"]}'
```

Save the `secret` (`whsec_…`) from the response and [verify each delivery](https://kibanda.africa/docs/webhooks#verifying-signatures).

**4. Send a test order.** Message your shop's WhatsApp number, order something, and watch `order.created` arrive.

## Base URLs

| Environment | URL | Keys |
|---|---|---|
| Production | `https://api.kibanda.africa` | `kb_live_…` |
| Staging (test) | `https://api-staging.kibanda.africa` | `kb_test_…` |

## Conventions

- JSON in and out. Send `Content-Type: application/json`.
- Every object has an `id` (prefixed: `pr_`, `ct_`, `ord_`, `evt_`, `we_`) and an `object` type.
- Money: integer minor units with a `currency` (`KES`). Times: Unix seconds.
- Updates use `POST /v1/<objects>/<id>` (or `PATCH`) and change only the fields you send.
- Lists are newest first and [paginated](https://kibanda.africa/docs/pagination).
- Every POST accepts an [Idempotency-Key](https://kibanda.africa/docs/idempotency).
- Errors have a stable `type` and `code`; see [Errors](https://kibanda.africa/docs/errors).

## For AI agents and LLMs

These docs are built to be read by machines too:

- [`/llms.txt`](https://kibanda.africa/llms.txt) — an index of every page; [`/llms-full.txt`](https://kibanda.africa/llms-full.txt) — all of it in one file.
- Any page as Markdown: add `.md` to its URL (e.g. [`/docs/webhooks.md`](https://kibanda.africa/docs/webhooks.md)), or send `Accept: text/markdown`.
- The OpenAPI 3.1 spec: [`/v1/openapi.json`](https://kibanda.africa/v1/openapi.json).
- Error messages say what to do next, and every error links to its explanation.

## Reference

[Authentication](https://kibanda.africa/docs/authentication) · [Checkout sessions](https://kibanda.africa/docs/checkout-sessions) · [AI agents & MCP](https://kibanda.africa/docs/agents) · [Ads & attribution](https://kibanda.africa/docs/ads) · [Shopify & Odoo](https://kibanda.africa/docs/integrations) · [Payments](https://kibanda.africa/docs/payments) · [Errors](https://kibanda.africa/docs/errors) · [Idempotency](https://kibanda.africa/docs/idempotency) · [Pagination](https://kibanda.africa/docs/pagination) · [Webhooks](https://kibanda.africa/docs/webhooks) · [Products](https://kibanda.africa/docs/products) · [Customers](https://kibanda.africa/docs/customers) · [Orders](https://kibanda.africa/docs/orders) · [Events](https://kibanda.africa/docs/events) · [Webhook endpoints](https://kibanda.africa/docs/webhook-endpoints)