POST /v1/ecommerce/sales

POST

ecommerce

sales

Crear una venta

curl --request POST \
  --url https://api.keebai.com/v1/ecommerce/sales \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "items": [
    {
      "quantity": 1,
      "product_id": "<string>",
      "variant_id": "<string>",
      "sku": "<string>",
      "name": "<string>",
      "price": 123,
      "net_price": 123,
      "discount_percentage": 50,
      "exempt": true
    }
  ],
  "type": "sale",
  "branch_id": "<string>",
  "customer": {
    "customer_id": "<string>",
    "name": "<string>",
    "email": "<string>",
    "phone": "56912345678"
  },
  "payments": [
    {
      "method": "cash",
      "amount": 15000,
      "reference": "<string>",
      "installments": 2
    }
  ],
  "notes": "<string>",
  "sold_at": "<string>",
  "currency": "CLP"
}
'

import requests

url = "https://api.keebai.com/v1/ecommerce/sales"

payload = {
    "items": [
        {
            "quantity": 1,
            "product_id": "<string>",
            "variant_id": "<string>",
            "sku": "<string>",
            "name": "<string>",
            "price": 123,
            "net_price": 123,
            "discount_percentage": 50,
            "exempt": True
        }
    ],
    "type": "sale",
    "branch_id": "<string>",
    "customer": {
        "customer_id": "<string>",
        "name": "<string>",
        "email": "<string>",
        "phone": "56912345678"
    },
    "payments": [
        {
            "method": "cash",
            "amount": 15000,
            "reference": "<string>",
            "installments": 2
        }
    ],
    "notes": "<string>",
    "sold_at": "<string>",
    "currency": "CLP"
}
headers = {
    "idempotency-key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'idempotency-key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: [
      {
        quantity: 1,
        product_id: '<string>',
        variant_id: '<string>',
        sku: '<string>',
        name: '<string>',
        price: 123,
        net_price: 123,
        discount_percentage: 50,
        exempt: true
      }
    ],
    type: 'sale',
    branch_id: '<string>',
    customer: {
      customer_id: '<string>',
      name: '<string>',
      email: '<string>',
      phone: '56912345678'
    },
    payments: [{method: 'cash', amount: 15000, reference: '<string>', installments: 2}],
    notes: '<string>',
    sold_at: '<string>',
    currency: 'CLP'
  })
};

fetch('https://api.keebai.com/v1/ecommerce/sales', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.keebai.com/v1/ecommerce/sales",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'quantity' => 1,
                'product_id' => '<string>',
                'variant_id' => '<string>',
                'sku' => '<string>',
                'name' => '<string>',
                'price' => 123,
                'net_price' => 123,
                'discount_percentage' => 50,
                'exempt' => true
        ]
    ],
    'type' => 'sale',
    'branch_id' => '<string>',
    'customer' => [
        'customer_id' => '<string>',
        'name' => '<string>',
        'email' => '<string>',
        'phone' => '56912345678'
    ],
    'payments' => [
        [
                'method' => 'cash',
                'amount' => 15000,
                'reference' => '<string>',
                'installments' => 2
        ]
    ],
    'notes' => '<string>',
    'sold_at' => '<string>',
    'currency' => 'CLP'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "idempotency-key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.keebai.com/v1/ecommerce/sales"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"quantity\": 1,\n      \"product_id\": \"<string>\",\n      \"variant_id\": \"<string>\",\n      \"sku\": \"<string>\",\n      \"name\": \"<string>\",\n      \"price\": 123,\n      \"net_price\": 123,\n      \"discount_percentage\": 50,\n      \"exempt\": true\n    }\n  ],\n  \"type\": \"sale\",\n  \"branch_id\": \"<string>\",\n  \"customer\": {\n    \"customer_id\": \"<string>\",\n    \"name\": \"<string>\",\n    \"email\": \"<string>\",\n    \"phone\": \"56912345678\"\n  },\n  \"payments\": [\n    {\n      \"method\": \"cash\",\n      \"amount\": 15000,\n      \"reference\": \"<string>\",\n      \"installments\": 2\n    }\n  ],\n  \"notes\": \"<string>\",\n  \"sold_at\": \"<string>\",\n  \"currency\": \"CLP\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("idempotency-key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.keebai.com/v1/ecommerce/sales")
  .header("idempotency-key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"quantity\": 1,\n      \"product_id\": \"<string>\",\n      \"variant_id\": \"<string>\",\n      \"sku\": \"<string>\",\n      \"name\": \"<string>\",\n      \"price\": 123,\n      \"net_price\": 123,\n      \"discount_percentage\": 50,\n      \"exempt\": true\n    }\n  ],\n  \"type\": \"sale\",\n  \"branch_id\": \"<string>\",\n  \"customer\": {\n    \"customer_id\": \"<string>\",\n    \"name\": \"<string>\",\n    \"email\": \"<string>\",\n    \"phone\": \"56912345678\"\n  },\n  \"payments\": [\n    {\n      \"method\": \"cash\",\n      \"amount\": 15000,\n      \"reference\": \"<string>\",\n      \"installments\": 2\n    }\n  ],\n  \"notes\": \"<string>\",\n  \"sold_at\": \"<string>\",\n  \"currency\": \"CLP\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.keebai.com/v1/ecommerce/sales")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"quantity\": 1,\n      \"product_id\": \"<string>\",\n      \"variant_id\": \"<string>\",\n      \"sku\": \"<string>\",\n      \"name\": \"<string>\",\n      \"price\": 123,\n      \"net_price\": 123,\n      \"discount_percentage\": 50,\n      \"exempt\": true\n    }\n  ],\n  \"type\": \"sale\",\n  \"branch_id\": \"<string>\",\n  \"customer\": {\n    \"customer_id\": \"<string>\",\n    \"name\": \"<string>\",\n    \"email\": \"<string>\",\n    \"phone\": \"56912345678\"\n  },\n  \"payments\": [\n    {\n      \"method\": \"cash\",\n      \"amount\": 15000,\n      \"reference\": \"<string>\",\n      \"installments\": 2\n    }\n  ],\n  \"notes\": \"<string>\",\n  \"sold_at\": \"<string>\",\n  \"currency\": \"CLP\"\n}"

response = http.request(request)
puts response.read_body

{
  "sale": {
    "_id": "<string>",
    "sale_number": 123,
    "status": "completed",
    "payment_status": "pending",
    "currency": "<string>",
    "customer": {
      "customer_id": "<string>",
      "name": "<string>",
      "email": "<string>",
      "phone": "56912345678"
    },
    "items": [
      {
        "quantity": 1,
        "product_id": "<string>",
        "variant_id": "<string>",
        "sku": "<string>",
        "name": "<string>",
        "price": 123,
        "net_price": 123,
        "discount_percentage": 50,
        "commissionee": {
          "id": "<string>",
          "name": "<string>"
        },
        "exempt": true
      }
    ],
    "amounts": {
      "service_subtotal": 123,
      "products_subtotal": 123,
      "custom_subtotal": 123,
      "net_subtotal": 123,
      "tax_amount": 123,
      "tip": 123,
      "total": 123
    },
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "payment_method": "<string>",
    "branch_id": "<string>",
    "notes": "<string>",
    "paid_at": "2023-11-07T05:31:56Z",
    "cancelled_at": "2023-11-07T05:31:56Z",
    "refunded_at": "2023-11-07T05:31:56Z"
  },
  "dte": {
    "issued": [
      {
        "sale_id": "<string>",
        "document": "invoice",
        "type": 123,
        "folio": 123,
        "document_id": "<string>",
        "status": "<string>",
        "net": 123,
        "exempt": 123,
        "tax": 123,
        "total": 123,
        "due_date": "<string>"
      }
    ],
    "failed": [
      {
        "sale_id": "<string>",
        "reason": "<string>",
        "message": "<string>"
      }
    ]
  }
}

Creates a sale in Keebai. Stock is deducted from the branch, commissions are calculated, and, if you pass dte, the electronic tax document is issued right after. It is also the way to issue an invoice: a free line with a net price, a known customer RUT and a payment method are enough. Everything that can fail — receiver data, payment, credit, branch, the document type, SKUs — is checked before the sale is created. A type: "internal" sale records internal consumption instead: products taken out of stock for the business’s own use, with no payments and no DTE.

Endpoint

POST https://api.keebai.com/v1/ecommerce/sales

Required scope

ecommerce:sales:write Sending dte also needs ecommerce:invoicing:issue. Without it the request fails with 403 INSUFFICIENT_SCOPE before the sale is created.

The invoicing scope comes from your role. Minting a token with ecommerce:invoicing:issue requires the permission to issue DTE in your Keebai role, unless you are the company owner or a superuser. See scopes.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer kbai_pk_<token>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Your own unique key for this sale. Retrying with the same key does not create a second sale.

Body

Field	Type	Required	Description
`type`	`string`	No	`sale` (default), a sale with payments, or `internal`, internal consumption: products only, no `payments`, no `dte`.
`branch_id`	`string`	No	Branch the sale happens in. Stock is deducted from it. Defaults to the company’s only active branch; with several, the request fails with `BRANCH_REQUIRED`.
`items`	`object[]`	Yes	Line items: a catalog product or a free line. See below.
`customer`	`object`	No	`customer_id`, `name`, `email`, `phone`.
`seller`	`object`	No	`user_id` and `name`, both required when you send `seller`.
`payments`	`object[]`	No	Payments of the sale. See below.
`notes`	`string`	No	Free text.
`sold_at`	`string`	No	ISO 8601 date-time of the sale.
`currency`	`string`	No	Currency of the amounts.
`dte`	`object`	No	Issue the electronic tax document after creating the sale. See below.

Item

Field	Type	Required	Description
`product_id`	`string`	No	`ObjectId` of the product. Send `product_id` or `sku` for a catalog product. Without both, the line is a free line.
`variant_id`	`string`	No	`ObjectId` of the variant.
`sku`	`string`	No	SKU or barcode. Resolves the product and variant without sending `product_id`.
`name`	`string`	Conditional	Line name. Defaults to the product’s. Required on a free line.
`quantity`	`number`	Yes	Units.
`price`	`number`	Conditional	Unit price, VAT included. Send `price` or `net_price`, not both. Without either, a product line takes the product’s, variant’s, or price list’s price. A free line needs one of them.
`net_price`	`number`	Conditional	Unit price before VAT, as you quote a business. The document shows exactly this net.
`discount_percentage`	`number`	No	Discount on the line, in percent.
`commissionee`	`object`	No	Who earns the commission of the line: `id` and `name`.
`exempt`	`boolean`	No	The line is exempt from VAT.

Payment

Field	Type	Required	Description
`method`	`string`	Yes	Payment method.
`amount`	`number`	Conditional	Amount paid. With a single payment you can leave it out: the sale total is charged. With several payments each one needs its amount.
`reference`	`string`	No	External reference, such as a voucher number.
`installments`	`number`	No	Installments.

DTE

Field	Type	Required	Description
`document`	`string`	Yes	`receipt` (boleta), `exempt_receipt` (boleta exenta), `invoice` (factura), or `exempt_invoice` (factura exenta).
`receiver`	`object`	Conditional	`rut`, `legal_name`, `activity`, `address`, `commune`, `email?`. Required for `invoice` and `exempt_invoice`. For a RUT the company invoiced before, `rut` alone is enough: the rest is filled in from the stored data, and any field you send overrides it.
`due_date`	`string`	No	`YYYY-MM-DD`. Due date of an invoice issued on credit, on a sale that is not fully paid. Defaults to today plus the company’s credit days. Ignored when the sale is paid.

Check which documents your company can issue today, and whether it allows credit invoices, with GET /v1/ecommerce/invoicing/types.

Example requests

curl -X POST https://api.keebai.com/v1/ecommerce/sales \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-01-ticket-99120" \
  -d '{
    "branch_id": "br_01",
    "items": [
      { "sku": "RUN-PRO-42-NEG", "quantity": 1 },
      { "product_id": "65d3e4f5a6b7c8d9e0f1a2b9", "quantity": 2, "price": 4990, "discount_percentage": 10 }
    ],
    "customer": { "name": "Juan Pérez", "email": "juan@example.com", "phone": "56912345678" },
    "payments": [{ "method": "card", "amount": 68972, "reference": "voucher-4411" }],
    "dte": { "document": "receipt" }
  }'

curl -X POST https://api.keebai.com/v1/ecommerce/sales \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "name": "Consulting hours", "quantity": 2, "net_price": 150000 }],
    "payments": [{ "method": "transfer", "reference": "TRX-8812" }],
    "dte": { "document": "invoice", "receiver": { "rut": "76123456-7" } }
  }'

curl -X POST https://api.keebai.com/v1/ecommerce/sales \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "branch_id": "br_01",
    "items": [{ "sku": "RUN-PRO-42-NEG", "quantity": 3 }],
    "payments": [{ "method": "transfer", "amount": 179970 }],
    "dte": {
      "document": "invoice",
      "receiver": {
        "rut": "76123456-7",
        "legal_name": "Comercial Ejemplo SpA",
        "activity": "Venta al por menor",
        "address": "Av. Libertador 1234",
        "commune": "Santiago",
        "email": "facturas@ejemplo.cl"
      }
    }
  }'

curl -X POST https://api.keebai.com/v1/ecommerce/sales \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: consulting-2026-11" \
  -d '{
    "items": [
      { "name": "Consulting hours", "quantity": 2, "net_price": 150000 },
      { "name": "Filing fee", "quantity": 1, "net_price": 5000, "exempt": true }
    ],
    "dte": {
      "document": "invoice",
      "due_date": "2026-12-10",
      "receiver": { "rut": "76123456-7" }
    }
  }'

curl -X POST https://api.keebai.com/v1/ecommerce/sales \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "internal",
    "branch_id": "br_01",
    "items": [{ "sku": "SHAMPOO-500", "quantity": 1 }],
    "notes": "Uso en lavado"
  }'

JavaScript

const response = await fetch("https://api.keebai.com/v1/ecommerce/sales", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": ticketId,
  },
  body: JSON.stringify({
    branch_id: "br_01",
    items: [{ sku: "RUN-PRO-42-NEG", quantity: 1 }],
    payments: [{ method: "cash", amount: 59990 }],
    dte: { document: "receipt" },
  }),
});
const { sale, dte } = await response.json();

Python

import os, requests

resp = requests.post(
    "https://api.keebai.com/v1/ecommerce/sales",
    headers={
        "Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}",
        "Idempotency-Key": ticket_id,
    },
    json={
        "branch_id": "br_01",
        "items": [{"sku": "RUN-PRO-42-NEG", "quantity": 1}],
        "payments": [{"method": "cash", "amount": 59990}],
        "dte": {"document": "receipt"},
    },
    timeout=30,
)
resp.raise_for_status()
result = resp.json()

Response

201 Created

sale has the same shape as GET /v1/ecommerce/sales/{id}. dte is present only when you sent dte.

{
  "sale": {
    "_id": "65e4f5a6b7c8d9e0f1a2b3c4",
    "sale_number": 1043,
    "status": "completed",
    "payment_status": "paid",
    "currency": "CLP",
    "items": [
      {
        "kind": "product",
        "name": "Zapatilla Runner Pro",
        "quantity": 1,
        "unit_price": 59990,
        "subtotal": 59990
      }
    ],
    "amounts": {
      "total": 59990
    },
    "branch_id": "br_01",
    "created_at": "2026-11-04T14:31:07.221Z"
  },
  "dte": {
    "issued": [
      {
        "sale_id": "65e4f5a6b7c8d9e0f1a2b3c4",
        "document": "receipt",
        "type": 39,
        "folio": 15422,
        "document_id": "6653e4f5a6b7c8d9e0f1a2b3",
        "status": "uploaded",
        "net": 50412,
        "exempt": 0,
        "tax": 9578,
        "total": 59990
      }
    ],
    "failed": []
  }
}

Field	Type	Description
`sale`	`object`	The created sale.
`dte.issued[]`	`object[]`	Documents issued: `sale_id`, `document`, `type` (SII code), `folio`, `document_id`, `status`, `net`, `exempt`, `tax`, `total`, and `due_date` for an invoice on credit.
`dte.failed[]`	`object[]`	Documents that could not be issued: `sale_id`, `reason` (the error code), `message?`. The reasons are listed in `POST /v1/ecommerce/sales/{id}/dte`.

400 Bad Request

The body does not match the schema, a field the endpoint does not accept, or one of these. Nothing is created.

`code`	Meaning
`SALE_ITEM_CUSTOM_INCOMPLETE`	A free line (no `product_id` and no `sku`) is missing `name`, or has neither `price` nor `net_price`.
`SALE_ITEM_INVALID`	A line has both `price` and `net_price`.
`PAYMENT_AMOUNT_REQUIRED`	Several payments, and one of them has no `amount`.
`PAYMENT_REQUIRED`	A `receipt` or `exempt_receipt` on a sale that is not fully paid. `pending` tells you what is missing when payments were sent.
`DUE_DATE_INVALID`	`due_date` is not `YYYY-MM-DD` or is before today.
`EXEMPT_DOCUMENT_REQUIRED`	Every line is exempt: use `exempt_invoice` or `exempt_receipt`.
`BRANCH_REQUIRED`	No `branch_id`, and the company has no active branch or more than one. `branches` lists them.
`INTERNAL_SALE_PAYMENTS_NOT_ALLOWED`	A `type: "internal"` sale carried `payments`.
`INTERNAL_SALE_DTE_NOT_ALLOWED`	A `type: "internal"` sale carried `dte`.
`INTERNAL_SALE_PRODUCTS_ONLY`	A `type: "internal"` sale carried a free line. Internal consumption only takes catalog products.

401 Unauthorized

Missing, invalid, revoked, or expired token.

403 Forbidden

INSUFFICIENT_SCOPE — the token does not have ecommerce:sales:write, or it sent dte without ecommerce:invoicing:issue. Nothing is created.

422 Unprocessable Entity

`code`	Meaning
`RECEIVER_DATA_REQUIRED`	The invoice receiver is incomplete and the RUT has no stored data to fill it. `missing` lists the fields.
`CREDIT_NOT_ENABLED`	An `invoice` or `exempt_invoice` on a sale that is not fully paid, and the company has not enabled credit invoices.
`DOCUMENT_NOT_AVAILABLE`	The company cannot issue that document today. `available` lists the ones it can.
`SKU_NOT_FOUND`	No product has that `sku`.
`SKU_AMBIGUOUS`	The `sku` matches more than one product.
`INVALID_PAYMENT`	A payment is not valid for the company — for example a method it does not accept.
`STOCK_INSUFFICIENT_IN_BRANCH`	The branch does not have enough stock for one of the items.

502 Bad Gateway

ECOMMERCE_UPSTREAM_ERROR — the ecommerce service could not answer.

Operational notes

Send an Idempotency-Key from a point of sale. A timeout does not tell you whether the sale was created. Retrying with the same key returns 201 with the original sale and creates nothing new; without it, a retry can double the sale and the stock deduction.
Errors are caught before anything is created. Every 400 and 422 above leaves no sale and no stock movement behind.
A failed confirmation leaves nothing behind. If the sale cannot be confirmed — for example INVALID_PAYMENT or STOCK_INSUFFICIENT_IN_BRANCH — the cart is discarded and the error is returned.
A failed DTE does not undo the sale. The sale stays created and the failure comes back in dte.failed. Fix the cause and issue it later with POST /v1/ecommerce/sales/{id}/dte.
A receipt needs a paid sale. A receipt whose payments do not cover the sale fails with PAYMENT_REQUIRED before the sale is confirmed.
An invoice can go on credit. When the company enables credit invoices in Sales › Settings, an invoice or exempt_invoice on a sale that is not fully paid is issued with a due date (due_date, or today plus the company’s credit days). Otherwise it fails with CREDIT_NOT_ENABLED and nothing is created. Record the payment later from the Keebai portal or with the MCP tool keebai_ecommerce_sale_payment_add.
Net prices are exact. With net_price the document shows exactly that net. A product line without its own price in the same sale keeps the catalog price it has at that moment.
internal never issues a DTE. Internal consumption has no payments and no tax document; it only moves stock.
Lines are catalog products or free lines. Send product_id (with variant_id when it has variants) or sku for a product; without price, net_price or name, the product’s are used. A line with neither product_id nor sku is a free line, such as a service or a charge outside the catalog: it needs name and a price, and moves no stock.
Commissions are calculated on the sale. commissionee on a line decides who earns it.

Authorizations

Authorization

string

header

required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Headers

idempotency-key

string

required

Idempotency-Key

string

Identificador único de la venta para reintentos. Sin él se genera uno

Body

application/json

items

object[]

required

Show child attributes

type

enum<string>

default:sale

sale venta normal con pagos; internal venta interna, solo productos, sin pagos ni DTE

Available options:

sale,

internal

branch_id

string

Sucursal de la venta. Sin ella se usa la única sucursal activa de la empresa

customer

object

Show child attributes

seller

object

Show child attributes

payments

object[]

Show child attributes

notes

string

Maximum string length: 1000

sold_at

string

Fecha de la venta, ISO 8601

currency

string

default:CLP

Example:

"CLP"

dte

object

Documento tributario a emitir después de confirmar la venta. Si falla, la venta queda igual y el error va en dte.failed

Show child attributes

Response

201 - application/json

sale

object

required

Show child attributes

dte

object

Solo cuando se pidió dte

Show child attributes

Crear una venta

curl --request POST \
  --url https://api.keebai.com/v1/ecommerce/sales \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "items": [
    {
      "quantity": 1,
      "product_id": "<string>",
      "variant_id": "<string>",
      "sku": "<string>",
      "name": "<string>",
      "price": 123,
      "net_price": 123,
      "discount_percentage": 50,
      "exempt": true
    }
  ],
  "type": "sale",
  "branch_id": "<string>",
  "customer": {
    "customer_id": "<string>",
    "name": "<string>",
    "email": "<string>",
    "phone": "56912345678"
  },
  "payments": [
    {
      "method": "cash",
      "amount": 15000,
      "reference": "<string>",
      "installments": 2
    }
  ],
  "notes": "<string>",
  "sold_at": "<string>",
  "currency": "CLP"
}
'

import requests

url = "https://api.keebai.com/v1/ecommerce/sales"

payload = {
    "items": [
        {
            "quantity": 1,
            "product_id": "<string>",
            "variant_id": "<string>",
            "sku": "<string>",
            "name": "<string>",
            "price": 123,
            "net_price": 123,
            "discount_percentage": 50,
            "exempt": True
        }
    ],
    "type": "sale",
    "branch_id": "<string>",
    "customer": {
        "customer_id": "<string>",
        "name": "<string>",
        "email": "<string>",
        "phone": "56912345678"
    },
    "payments": [
        {
            "method": "cash",
            "amount": 15000,
            "reference": "<string>",
            "installments": 2
        }
    ],
    "notes": "<string>",
    "sold_at": "<string>",
    "currency": "CLP"
}
headers = {
    "idempotency-key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'idempotency-key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: [
      {
        quantity: 1,
        product_id: '<string>',
        variant_id: '<string>',
        sku: '<string>',
        name: '<string>',
        price: 123,
        net_price: 123,
        discount_percentage: 50,
        exempt: true
      }
    ],
    type: 'sale',
    branch_id: '<string>',
    customer: {
      customer_id: '<string>',
      name: '<string>',
      email: '<string>',
      phone: '56912345678'
    },
    payments: [{method: 'cash', amount: 15000, reference: '<string>', installments: 2}],
    notes: '<string>',
    sold_at: '<string>',
    currency: 'CLP'
  })
};

fetch('https://api.keebai.com/v1/ecommerce/sales', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.keebai.com/v1/ecommerce/sales",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'quantity' => 1,
                'product_id' => '<string>',
                'variant_id' => '<string>',
                'sku' => '<string>',
                'name' => '<string>',
                'price' => 123,
                'net_price' => 123,
                'discount_percentage' => 50,
                'exempt' => true
        ]
    ],
    'type' => 'sale',
    'branch_id' => '<string>',
    'customer' => [
        'customer_id' => '<string>',
        'name' => '<string>',
        'email' => '<string>',
        'phone' => '56912345678'
    ],
    'payments' => [
        [
                'method' => 'cash',
                'amount' => 15000,
                'reference' => '<string>',
                'installments' => 2
        ]
    ],
    'notes' => '<string>',
    'sold_at' => '<string>',
    'currency' => 'CLP'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "idempotency-key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.keebai.com/v1/ecommerce/sales"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"quantity\": 1,\n      \"product_id\": \"<string>\",\n      \"variant_id\": \"<string>\",\n      \"sku\": \"<string>\",\n      \"name\": \"<string>\",\n      \"price\": 123,\n      \"net_price\": 123,\n      \"discount_percentage\": 50,\n      \"exempt\": true\n    }\n  ],\n  \"type\": \"sale\",\n  \"branch_id\": \"<string>\",\n  \"customer\": {\n    \"customer_id\": \"<string>\",\n    \"name\": \"<string>\",\n    \"email\": \"<string>\",\n    \"phone\": \"56912345678\"\n  },\n  \"payments\": [\n    {\n      \"method\": \"cash\",\n      \"amount\": 15000,\n      \"reference\": \"<string>\",\n      \"installments\": 2\n    }\n  ],\n  \"notes\": \"<string>\",\n  \"sold_at\": \"<string>\",\n  \"currency\": \"CLP\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("idempotency-key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.keebai.com/v1/ecommerce/sales")
  .header("idempotency-key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"quantity\": 1,\n      \"product_id\": \"<string>\",\n      \"variant_id\": \"<string>\",\n      \"sku\": \"<string>\",\n      \"name\": \"<string>\",\n      \"price\": 123,\n      \"net_price\": 123,\n      \"discount_percentage\": 50,\n      \"exempt\": true\n    }\n  ],\n  \"type\": \"sale\",\n  \"branch_id\": \"<string>\",\n  \"customer\": {\n    \"customer_id\": \"<string>\",\n    \"name\": \"<string>\",\n    \"email\": \"<string>\",\n    \"phone\": \"56912345678\"\n  },\n  \"payments\": [\n    {\n      \"method\": \"cash\",\n      \"amount\": 15000,\n      \"reference\": \"<string>\",\n      \"installments\": 2\n    }\n  ],\n  \"notes\": \"<string>\",\n  \"sold_at\": \"<string>\",\n  \"currency\": \"CLP\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.keebai.com/v1/ecommerce/sales")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"quantity\": 1,\n      \"product_id\": \"<string>\",\n      \"variant_id\": \"<string>\",\n      \"sku\": \"<string>\",\n      \"name\": \"<string>\",\n      \"price\": 123,\n      \"net_price\": 123,\n      \"discount_percentage\": 50,\n      \"exempt\": true\n    }\n  ],\n  \"type\": \"sale\",\n  \"branch_id\": \"<string>\",\n  \"customer\": {\n    \"customer_id\": \"<string>\",\n    \"name\": \"<string>\",\n    \"email\": \"<string>\",\n    \"phone\": \"56912345678\"\n  },\n  \"payments\": [\n    {\n      \"method\": \"cash\",\n      \"amount\": 15000,\n      \"reference\": \"<string>\",\n      \"installments\": 2\n    }\n  ],\n  \"notes\": \"<string>\",\n  \"sold_at\": \"<string>\",\n  \"currency\": \"CLP\"\n}"

response = http.request(request)
puts response.read_body

{
  "sale": {
    "_id": "<string>",
    "sale_number": 123,
    "status": "completed",
    "payment_status": "pending",
    "currency": "<string>",
    "customer": {
      "customer_id": "<string>",
      "name": "<string>",
      "email": "<string>",
      "phone": "56912345678"
    },
    "items": [
      {
        "quantity": 1,
        "product_id": "<string>",
        "variant_id": "<string>",
        "sku": "<string>",
        "name": "<string>",
        "price": 123,
        "net_price": 123,
        "discount_percentage": 50,
        "commissionee": {
          "id": "<string>",
          "name": "<string>"
        },
        "exempt": true
      }
    ],
    "amounts": {
      "service_subtotal": 123,
      "products_subtotal": 123,
      "custom_subtotal": 123,
      "net_subtotal": 123,
      "tax_amount": 123,
      "tip": 123,
      "total": 123
    },
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "payment_method": "<string>",
    "branch_id": "<string>",
    "notes": "<string>",
    "paid_at": "2023-11-07T05:31:56Z",
    "cancelled_at": "2023-11-07T05:31:56Z",
    "refunded_at": "2023-11-07T05:31:56Z"
  },
  "dte": {
    "issued": [
      {
        "sale_id": "<string>",
        "document": "invoice",
        "type": 123,
        "folio": 123,
        "document_id": "<string>",
        "status": "<string>",
        "net": 123,
        "exempt": 123,
        "tax": 123,
        "total": 123,
        "due_date": "<string>"
      }
    ],
    "failed": [
      {
        "sale_id": "<string>",
        "reason": "<string>",
        "message": "<string>"
      }
    ]
  }
}

Get started

Products

Inventory

Carts

Sales

Electronic invoicing

POST /v1/ecommerce/sales

Endpoint

Required scope

Headers

Body

Item

Payment

DTE

Example requests

Response

201 Created

400 Bad Request

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

502 Bad Gateway

Operational notes

Authorizations

Headers

Body

Response

​Endpoint

​Required scope

​Headers

​Body

​Item

​Payment

​DTE

​Example requests

​Response

​201 Created

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​502 Bad Gateway

​Operational notes

Authorizations

Headers

Body

Response

Endpoint

Required scope

Headers

Body

Item

Payment

DTE

Example requests

Response

201 Created

400 Bad Request

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

502 Bad Gateway

Operational notes