Kommo plugin

• The account subdomain. Every account is served from its own host: acme for acme.kommo.com, under /api/v4. Connect delivers it as the subdomain credential; the plugin option of the same name overrides it. A call with neither throws before any request is sent.
• A pipeline and stage. A lead’s pipeline_id and status_id come from pipelines.list. A lead created without them lands in the first stage of the main pipeline.

• Timestamps are Unix seconds. created_at, updated_at, closed_at, closest_task_at and a task’s complete_till are integers counting seconds, not ISO strings. The plugin passes them through as Kommo sends them.
• Paging is by page number. A list takes page and limit (250 at most) and returns a _page and _links block. The plugin adds next_page, which is null on the last page. Kommo answers an empty list with 204 No Content, which the plugin returns as an empty page.
• Filters are bracketed query keys. pipeline_id and the date filters become filter[pipeline_id][] and filter[created_at][from] on the wire, which is how Kommo documents them. The date filters take Unix seconds. A stage filter is status_id together with its pipeline_id, sent as filter[statuses][0][...]; Kommo allows only one stage in one pipeline per request.
• A write takes an array. leads.create, contacts.create and tasks.create post up to 250 entities at once, and the update routes are PATCH with each entity carrying its id. A field left out of an update is untouched.
• Custom field values go by field_id or field_code. The plugin refuses a value that names neither, because Kommo would reject it. A value’s type follows its field_type, so a date_time field takes a Unix timestamp.
• A new contact needs a name. name, or first_name and last_name; a contact created with neither is refused before the call. An update can change any one field.
• A task needs a deadline. complete_till is required, in Unix seconds.
• Rate limits. Kommo allows seven requests a second and answers 429 past that, with Retry-After, which the plugin honours before backing off. A 402 means the account’s paid or trial period has ended, and is not retried. Only reads are replayed after a 5xx, because a retried lead create would make a second lead.
• Webhooks. Kommo does send webhooks, but this plugin does not receive them; that is a separate integration surface.

• 14 typed API operations

Setup

npm install corsair @corsair-dev/kommo better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/kommo better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/kommo better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/kommo better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { kommo } from '@corsair-dev/kommo';

export const corsair = createCorsair({
	plugins: [
		kommo(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

kommo()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'kommo',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.kommo.api.leads.list({
	limit: 50,
	with: ['contacts'],
});

const tenant = corsair.withTenant('acme');
await tenant.kommo.api.leads.create({
	leads: [{ name: 'Acme renewal', price: 5000 }],
});

What’s next