Integration strategy: what the API covers now and next

What exists today, and what is planned

Available now, on the Enterprise plan:

• Integration credentials tied to your organisation, branch, role and fiscal year, so a key can only ever reach your own data.
• Per-request isolation: every call is routed to your organisation’s own database.
• A gateway guard that validates the credentials, the calling IP address, the timestamp and the nonce, and the signature on requests that change data.
• The products and billing endpoints, and webhooks for invoice created, invoice voided and adjustment approved.

Planned, and described on this page so you can plan for them: the wider inventory catalogue (reservations, transfers, purchase orders, goods receipt), payments and customers through the billing API, more webhook events, a logistics API, usage metrics and quotas, and usage-based pricing for integrations. None of these is available yet; when one ships it appears in the pages of this chapter.

The inventory catalogue

Inventory is the core record of products, stock and replenishment. Opening it lets an online store or an ERP keep its catalogue and stock in step with the counter.

Products:

• GET /api/v1/external/products: list products, with search. Available now; filtering by category and status is planned.
• GET /api/v1/external/products/:id: one product with its units, prices and tax rate. Planned.
• POST /api/v1/external/products: create a product. Planned.
• PUT /api/v1/external/products/:id: update a product. Available now.

Stock:

• GET /api/v1/external/products/stock: stock status. Available now as the low-stock summary; stock by branch is planned.
• POST /api/v1/external/products/adjust: submit a stock correction, which waits for approval like any adjustment. Available now.
• POST /api/v1/external/products/transfer: record a movement between warehouses or branches. Planned.
• POST /api/v1/external/products/reserve: hold stock for a cart or a sales order so it cannot be sold twice. Planned.

Procurement:

• GET /api/v1/external/purchase-orders: list pending and past purchase orders. Planned.
• POST /api/v1/external/goods-receipt: record a delivery from a supplier, updating stock and the ledger. Planned.

The billing catalogue

Opening billing lets an external sales channel (a website cart, a kiosk, another billing tool) send its sales into Kuver Books for tax, the invoice number and the books.

• POST /api/v1/external/billing/invoices: submit a sale; the invoice number and the tax record are created here. Available now.
• GET /api/v1/external/billing/invoices/:id: one invoice with its status and lines. Planned; the list endpoint is available now.
• PATCH /api/v1/external/billing/invoices/:id/void: void an invoice with a logged reason, in line with IRD guidance. Available now.
• POST /api/v1/external/billing/invoices/:id/payments: record a cash, card, QR or credit payment against an open invoice. Planned.
• POST /api/v1/external/billing/customers: create a customer profile, with its PAN for VAT records. Planned.
• Credit and debit notes: available now at their own endpoints; see Billing and invoices.

Webhook events in the billing domain: billing.invoice.created and billing.invoice.voided are live. billing.payment.received (invoice, payment mode, reference) and billing.refund.processed (refund, amount, original invoice) are planned.

Who owns the data when two systems connect

The hardest part of any integration is agreeing which system is the source of truth, so that stock is not counted twice and updates do not loop. Three models are supported in the design:

1. Inventory as the source of truth. Kuver Books owns stock levels, product data and prices. The external system, typically an online store, reads stock through the API or webhooks and submits invoices to Kuver Books when it sells.
2. Billing as the source of truth. An external ERP owns procurement, the product register and receivables. Kuver Books works as the transaction register, pushing invoice records to the ERP and taking its catalogue from it.
3. Hybrid. Product master data lives in the ERP; live stock and the day’s sales live in Kuver Books; the two sync on a schedule through message queues.

Decide the model before you build. Most shops with an online store want the first; a business that already runs an ERP wants the second or third.

How events move between systems

Integrations are event driven, so a slow third party never slows the counter. Every transaction or stock change puts an event on a queue; background workers deliver the webhooks from there, and the retry rules on the Webhooks page apply: exponential backoff, a dead-letter queue after the fifth failure, and an alert so a broken endpoint does not loop forever. Every integration request, its payload and its HTTP status are logged for troubleshooting.

Logistics, planned

For online orders, the plan is a logistics API that books, tracks and cancels deliveries with courier services in Nepal:

• POST /api/v1/external/logistics/shipments: book a pickup with the weight, the cash-on-delivery amount and the address.
• GET /api/v1/external/logistics/shipments/:id/track: the delivery status and its history.
• POST /api/v1/external/logistics/shipments/cancel: cancel a booking.

It will have webhook events for pickup, transit, delivered and failed. The flow it supports: a customer orders, the invoice is created, the booking is triggered and the label printed, the package is picked up, the courier reports transit, the customer receives it.

Standards

• REST over JSON, with path versioning (/api/v1/external/...); a new version is introduced only for a breaking change such as a removed field.
• Interactive OpenAPI documentation is planned so you can try routes from the browser.
• IP allow-listing per integration, rate limiting per key, and an audit log of every request. The current limits are on the Introduction page.
• The response envelope you get today is documented on the Introduction page. The planned error format adds a machine-readable code and per-field details alongside the message.

Pricing for integrations

API access is part of the Enterprise plan and is agreed with you; see pricing. A usage-based model with monthly tiers is under consideration for the future and will be published here if it is adopted.

In plain words

Think of Kuver Books as a locked warehouse. When an outside system wants to look inside, it shows a pass at the gate; the guard checks it, notes who came in and for which branch, and takes them straight to their own business’s room, never anyone else’s. The online store asks whether the coffee beans are in stock; the warehouse says forty-five bags, and the website shows that. A shopper buys two; the store tells the warehouse, which takes two off the shelf, records the payment and files the invoice. If a courier is connected, the warehouse tells them a parcel is ready, and their updates come back so you can see whether it is on its way, delivered, or failed.