Developers

Send orders to KinMol

This page is for delivery apps and POS systems that want to send orders to a restaurant in Nepal that uses KinMol. The order arrives on the restaurant's kitchen screen and is billed at the restaurant's own menu prices.

What the restaurant gives you

The restaurant switches the order feed on in KinMol, under Delivery apps. It then gives you two things: an address and a secret. Keep the secret private. Each restaurant has its own address and its own secret.

POST https://kinmol.com/api/orders/intake/<platform>/<hook key>

The platform is a short lowercase name such as foodmandu or pathao_food, using letters and underscores only. The hook key is a hexadecimal string that names the restaurant. Both are part of the address the restaurant gives you. Only POST is accepted.

Signing the request

Every request must carry the header x-signature. Its value is the HMAC-SHA256 of the raw request body, using the restaurant's secret as the key, written as lowercase hexadecimal. Use the body exactly as you send it, as UTF-8 text. Do not add a prefix such as sha256=.

There is no timestamp header and no time window. The signature covers the body only. Because the same order number is accepted once, it is safe to retry a request that did not get a reply.

import { createHmac } from "node:crypto";

const url = "https://kinmol.com/api/orders/intake/pathao_food/<hook key>";
const secret = process.env.KINMOL_SECRET; // the secret the restaurant gave you

const body = JSON.stringify({
  order: {
    id: "PF-88123",
    note: "Ring the bell twice",
    items: [
      { name: "Chicken Momo", sku: "MOMO-CHK", qty: 2, note: "Extra chutney" },
      { name: "Masala Tea", qty: 1 },
    ],
  },
});

// Sign the exact string you send. Do not re-serialise it.
const signature = createHmac("sha256", secret).update(body, "utf8").digest("hex");

const res = await fetch(url, {
  method: "POST",
  headers: { "content-type": "application/json", "x-signature": signature },
  body,
});
console.log(res.status, await res.json());

The body

Send JSON, up to 64 KB. You keep the field names you already use. Each restaurant saves a mapping in KinMol: a dotted path to each field. A number in a path reads an array position. KinMol needs these:

• An order number, up to 60 characters.
• An array of items, from 1 to 100 lines.
• On each line, a name and a quantity from 1 to 100.

These are optional: an item code on each line, a note on each line, and a note for the whole order. KinMol does not read a customer name or phone number from the body today. Put anything staff need to know in the order note.

A restaurant that maps the example body below would save these paths:

Order number     order.id
Items array      order.items
Item name        name
Item code        sku          (optional)
Quantity         qty
Line note        note         (optional)
Order note       order.note   (optional)

Prices in your body are ignored. KinMol bills each line at the restaurant's menu price. A line is matched to the menu by its code first, then by its name, ignoring case and punctuation. A name that matches two dishes is left for staff. A line that matches nothing is listed in the order note, and the order is still created. If no line matches, the order is refused with a 422.

Replies

A good reply looks like this. The error reply is one sentence saying what to fix.

{ "ok": true, "order_id": "…", "unmatched": [], "duplicate": false }

{ "ok": false, "error": "No items at \"order.items\"." }

Sending the same order twice

The same order number from the same app is accepted once. A second request with that number does not make a second bill. It returns the order already made, so you can retry without worry.

Testing

There is no test mode. A signed request that passes every check creates a real order. Ask the restaurant to send you the address and secret for a test setup, and use order numbers that start with TEST so staff can tell them apart.

Questions

Write to hello@kinmol.com. This page describes how KinMol accepts orders. It is not an offer of a partnership, and KinMol does not promise that any app will connect.