kommo-aiatende-api

SDK não oficial, moderno e totalmente tipado em TypeScript para a API V4 da Kommo CRM. Cobre todos os recursos documentados, normaliza inconsistências da API e oferece validações locais (pre-flight) para evitar erros HTTP desnecessários.

📦 Instalação

npm install kommo-aiatende-api
# ou
yarn add kommo-aiatende-api
# ou
pnpm add kommo-aiatende-api

🚀 Inicialização

import { KommoClient } from 'kommo-aiatende-api';

const client = new KommoClient({
  domain: 'meusubdominio', // apenas o subdomínio, sem ".kommo.com"
  accessToken: 'SEU_ACCESS_TOKEN',
});

// Atualizar o token dinamicamente (ex: após refresh OAuth)
client.setAccessToken('NOVO_TOKEN');

Nota: A biblioteca não gerencia o fluxo OAuth. Você deve implementar a renovação de tokens na sua infraestrutura.

🛡️ Tratamento de Erros

Todos os erros HTTP são convertidos em KommoApiError:

import { KommoApiError } from 'kommo-aiatende-api';

try {
  await client.leads.getById(999999);
} catch (err) {
  if (err instanceof KommoApiError) {
    console.log(err.status);  // número HTTP (ex: 404)
    console.log(err.title);   // título do erro
    console.log(err.detail);  // detalhe técnico
    console.log(err.raw);     // corpo bruto da resposta
  }
}

📋 Referência Completa da API

client.account

Parâmetros e configurações da conta Kommo.

| Método | Descrição | |--------|-----------| | get(params?) | Retorna informações da conta |

Parâmetros with disponíveis:

| Valor | Descrição | |-------|-----------| | amojo_id | ID da conta no serviço de chat | | amojo_rights | Direitos de chat (grupos e diretos) | | users_groups | Grupos de usuários da conta | | task_types | Tipos de tarefas configurados | | version | Versão atual da Kommo | | entity_names | Nomes de entidades com traduções | | datetime_settings | Configurações de data/hora | | drive_url | URL base do serviço de arquivos (Files API) |

const account = await client.account.get({
  with: ['amojo_id', 'drive_url', 'version'],
});

console.log(account.name);
console.log(account.subdomain);
console.log(account.amojo_id);
console.log(account._embedded?.drive_url);

client.leads

| Método | Descrição | |--------|-----------| | list(params?) | Lista leads com filtros e paginação | | getById(id, params?) | Retorna um lead por ID (ou null se não encontrado) | | create(items) | Cria um ou mais leads | | update(items) | Atualiza leads em lote | | updateOne(id, payload) | Atualiza um único lead | | createComplex(items) | Cria leads com contatos e empresas em uma requisição | | listLossReasons() | Lista os motivos de perda configurados | | getLossReasonById(id) | Retorna um motivo de perda por ID |

Parâmetros de listagem (ListLeadsParams):

| Parâmetro | Tipo | Descrição | |-----------|------|-----------| | page | number | Página | | limit | number | Itens por página | | query | string | Busca textual | | with | string \| string[] | Blocos opcionais (contacts, loss_reason, catalog_elements, is_price_modified_by_robot, only_deleted, source_id) | | filter_id | number[] | Filtro por IDs | | filter_name | string[] | Filtro por nomes | | filter_price | { from?, to? } | Filtro por valor | | filter_pipeline_id | number[] | Filtro por pipeline | | filter_responsible_user_id | number[] | Filtro por responsável | | filter_statuses | { pipeline_id, status_id }[] | Filtro por estágio | | filter_created_at_from / _to | number | Unix timestamp de criação | | filter_updated_at_from / _to | number | Unix timestamp de atualização | | filter_closed_at_from / _to | number | Unix timestamp de fechamento | | filter_closest_task_at_from / _to | number | Unix timestamp da próxima tarefa | | order_created_at | 'asc' \| 'desc' | Ordenação por criação | | order_updated_at | 'asc' \| 'desc' | Ordenação por atualização | | order_id | 'asc' \| 'desc' | Ordenação por ID |

const { _embedded } = await client.leads.list({
  with: ['contacts'],
  filter_pipeline_id: [1234],
  filter_statuses: [{ pipeline_id: 1234, status_id: 5678 }],
  order_created_at: 'desc',
  page: 1,
  limit: 50,
});

const leads = _embedded?.leads ?? [];

client.contacts

| Método | Descrição | |--------|-----------| | list(params?) | Lista contatos | | getById(id, params?) | Retorna contato por ID (ou null) | | create(items) | Cria um ou mais contatos | | update(items) | Atualiza contatos em lote | | updateOne(id, payload) | Atualiza um único contato |

Parâmetros with disponíveis: leads, catalog_elements

Filtros disponíveis: filter_id, filter_name, filter_created_by, filter_updated_by, filter_responsible_user_id, filter_created_at_from/to, filter_updated_at_from/to, filter_closest_task_at_from/to

client.companies

| Método | Descrição | |--------|-----------| | list(params?) | Lista empresas | | getById(id, params?) | Retorna empresa por ID (ou null) | | create(items) | Cria uma ou mais empresas | | update(items) | Atualiza empresas em lote | | updateOne(id, payload) | Atualiza uma única empresa |

Parâmetros with disponíveis: leads, contacts, catalog_elements

Filtros disponíveis: filter_id, filter_name, filter_created_by, filter_updated_by, filter_responsible_user_id, filter_created_at_from/to, filter_updated_at_from/to, filter_closest_task_at_from/to

client.unsorted

Gerencia leads da caixa de entrada (Unsorted).

| Método | Descrição | |--------|-----------| | list(params?) | Lista leads não classificados | | getByUid(uid) | Retorna um lead não classificado pelo UID | | createSip(items) | Cria leads via integração SIP | | createForms(items) | Cria leads via formulário | | accept(uid, payload?) | Aceita um lead (move para pipeline) | | decline(uid, payload?) | Recusa e remove um lead não classificado | | link(uid, payload) | Vincula o lead a uma entidade existente | | summary(params?) | Resumo estatístico dos leads não classificados |

// Aceitar um lead não classificado
await client.unsorted.accept('UID_DO_LEAD', {
  user_id: 123,
  status_id: 456,
});

// Vincular a um lead existente
await client.unsorted.link('UID_DO_LEAD', {
  link: {
    entity_id: 9999,
    entity_type: 'leads',
  },
});

client.pipelines

Gerencia funis e estágios de leads.

| Método | Descrição | |--------|-----------| | list() | Lista todos os funis | | getById(id) | Retorna um funil por ID | | create(items) | Cria funis | | update(id, payload) | Atualiza um funil | | delete(id) | Remove um funil | | listStatuses(pipelineId, params?) | Lista estágios de um funil | | getStatusById(pipelineId, id, params?) | Retorna um estágio por ID | | createStatuses(pipelineId, items) | Cria estágios no funil | | updateStatus(pipelineId, id, payload) | Atualiza um estágio | | deleteStatus(pipelineId, id) | Remove um estágio |

Parâmetro with disponível para Status: 'descriptions'

⚠️ Validação local: Estágios aceitam no máximo 3 descrições, sem repetição de level, e cada descrição pode ter no máximo 1000 caracteres. A SDK valida antes de enviar.

client.tasks

| Método | Descrição | |--------|-----------| | list(params?) | Lista tarefas | | getById(id) | Retorna tarefa por ID | | create(items) | Cria tarefas | | update(items) | Atualiza tarefas em lote | | updateOne(id, payload) | Atualiza uma única tarefa |

Filtros disponíveis: filter_id, filter_responsible_user_id, filter_is_completed, filter_task_type, filter_entity_type, filter_entity_id, filter_updated_at_from/to

Ordenação: order_complete_till, order_created_at, order_id

client.notes

Notas são sempre escopadas por tipo de entidade (leads, contacts, companies).

| Método | Descrição | |--------|-----------| | listByEntity(entityType, entityId, params?) | Lista notas de uma entidade específica | | listByEntityType(entityType, params?) | Lista notas de todas as entidades do tipo | | getById(entityType, id) | Retorna uma nota por ID | | create(entityType, items) | Cria notas | | update(entityType, items) | Atualiza notas em lote | | updateOne(entityType, id, payload) | Atualiza uma única nota | | pin(entityType, id) | Fixa uma nota | | unpin(entityType, id) | Desafixa uma nota |

Tipos de nota (note_type): common, call_in, call_out, service_message, extended_service_message, geolocation, image, video, voice, doc, invoice, site_visit, messenger, sms, amolink, drive_file, chat_message, entre outros.

// Criar nota de texto em um lead
await client.notes.create('leads', {
  entity_id: 1234,
  note_type: 'common',
  params: { text: 'Cliente confirmou reunião.' },
});

// Criar nota de chamada
await client.notes.create('leads', {
  entity_id: 1234,
  note_type: 'call_in',
  params: {
    uniq: 'UUID_DA_CHAMADA',
    duration: 120,
    source: 'minha-ura',
    link: 'https://cdn.example.com/recording.mp3',
    phone: '+5511999999999',
  },
});

client.events

| Método | Descrição | |--------|-----------| | list(params?) | Lista eventos do log | | getById(id, params?) | Retorna um evento por ID | | listTypes(params?) | Lista os tipos de evento disponíveis |

Parâmetros with disponíveis: contact_name

Filtros disponíveis: filter_id, filter_created_by, filter_entity, filter_entity_id (exige filter_entity único), filter_type, filter_created_at_from/to, filter_value_before, filter_value_after

⚠️ Validação local: filter_entity_id só é aceito quando filter_entity contém exatamente um tipo de entidade.

client.catalogs

Gerencia listas (catálogos) e seus elementos.

| Método | Descrição | |--------|-----------| | list(params?) | Lista catálogos | | getById(id) | Retorna catálogo por ID | | create(items) | Cria catálogos | | update(items) | Atualiza catálogos em lote | | updateOne(id, payload) | Atualiza um único catálogo | | listElements(listId, params?) | Lista elementos do catálogo | | getElementById(listId, elementId) | Retorna elemento por ID | | createElements(listId, items) | Cria elementos no catálogo | | updateElements(listId, items) | Atualiza elementos em lote | | updateElementById(listId, elementId, payload) | Atualiza um único elemento |

// Listar elementos de um catálogo com busca textual
const { _embedded } = await client.catalogs.listElements(42, {
  query: 'Produto X',
  limit: 20,
});

client.customFields e client.customFieldGroups

client.customFields

| Método | Descrição | |--------|-----------| | listEntity(entityType) | Lista campos de uma entidade (leads, contacts, companies) | | getEntityById(entityType, id) | Retorna campo por ID | | createEntity(entityType, items) | Cria campos | | updateEntity(entityType, items) | Atualiza campos em lote | | updateEntityById(entityType, id, payload) | Atualiza um campo | | deleteEntity(entityType, id) | Remove um campo | | listList(listId) | Lista campos de um catálogo | | getListById(listId, customFieldId) | Retorna campo de catálogo por ID | | createList(listId, items) | Cria campos no catálogo | | updateList(listId, items) | Atualiza campos do catálogo em lote | | updateListById(listId, customFieldId, payload) | Atualiza um campo | | deleteList(listId, id) | Remove campo do catálogo |

client.customFieldGroups

| Método | Descrição | |--------|-----------| | list(entityType) | Lista grupos de campos | | getById(entityType, id) | Retorna grupo por ID | | create(entityType, items) | Cria grupos | | update(entityType, id, payload) | Atualiza um grupo | | delete(entityType, id) | Remove um grupo |

client.users e client.roles

client.users

| Método | Descrição | |--------|-----------| | list(params?) | Lista usuários | | getById(id, params?) | Retorna usuário por ID | | create(items) | Cria usuários (máximo 10 por requisição) |

Parâmetros with disponíveis: role, group, uuid, is_free, is_active, rights

client.roles

| Método | Descrição | |--------|-----------| | list(params?) | Lista funções/roles | | getById(id, params?) | Retorna role por ID | | create(items) | Cria roles | | update(items) | Atualiza roles em lote | | delete(id) | Remove uma role |

Parâmetros with disponíveis: users

client.tags

Tags são escopadas por tipo de entidade.

| Método | Descrição | |--------|-----------| | list(entityType, params?) | Lista tags da entidade | | create(entityType, items) | Cria tags | | updateForMany(entityType, items) | Atualiza tags de múltiplas entidades via batch PATCH | | updateForOne(entityType, id, payload) | Atualiza tags de uma entidade |

⚠️ Validação local: A propriedade color nas tags só é suportada para a entidade leads. Um aviso é emitido no console se usada em outros tipos.

// Criar tags coloridas para leads
await client.tags.create('leads', [
  { name: 'VIP', color: '#FF0000' },
  { name: 'Urgente', color: '#FF5E00' },
]);

// Substituir as tags de um contato específico
await client.tags.updateForOne('contacts', 1234, {
  _embedded: { tags: [{ id: 99 }, { name: 'Nova Tag' }] },
});

client.links

Gerencia vínculos entre entidades.

| Método | Descrição | |--------|-----------| | list(entity, entityId, params?) | Lista vínculos de uma entidade | | link(entity, entityId, items) | Cria vínculos | | unlink(entity, entityId, items) | Remove vínculos |

Entidades fonte suportadas: leads, contacts, companies

Filtros disponíveis:

| Parâmetro | Obs | |-----------|-----| | filter_to_entity_id | Deve ser usado junto com filter_to_entity_type | | filter_to_entity_type | Deve ser usado junto com filter_to_entity_id | | filter_to_catalog_id | Filtro por catálogo |

⚠️ Validação local: filter_to_entity_id e filter_to_entity_type devem ser fornecidos juntos. A SDK lança erro se apenas um deles for informado.

client.salesbots

| Método | Descrição | |--------|-----------| | list(params?) | Lista salesbots disponíveis | | run(botId, payload) | Executa um bot em um lead/contato | | runMany(items) | Executa múltiplos bots em lote (máx. 100) | | stop(botId, payload) | Para a execução de um bot | | continueWidgetExecution(bot, botId, continueId, payload) | Confirma execução de bloco de widget interativo |

⚠️ Validações locais:

• runMany limita a 100 itens por chamada.
• continueWidgetExecution limita execute_handlers a 10 itens.
• Handlers show com mais de 80 caracteres em value emitem aviso.
• Handlers show com mais de 25 botões lançam erro.

client.sources e client.websiteButtons

client.sources

| Método | Descrição | |--------|-----------| | list() | Lista fontes de captação | | getById(id) | Retorna fonte por ID | | create(items) | Cria fontes (máx. 100 por vez) | | updateOne(id, payload) | Atualiza uma fonte | | update(items) | Atualiza fontes em lote (máx. 100) | | deleteOne(id) | Remove uma fonte | | delete(items) | Remove fontes em lote |

client.websiteButtons

| Método | Descrição | |--------|-----------| | list(params?) | Lista botões de chat web | | getBySourceId(sourceId, params?) | Retorna botão por source ID | | create(payload) | Cria um botão de chat web | | connectOnlineChat(sourceId) | Conecta chat online ao botão | | update(sourceId, payload) | Atualiza um botão |

Parâmetros with disponíveis para botões: 'scripts'

⚠️ Validação local: Se trusted_websites não for informado e is_used_in_app não for true, a SDK emite aviso no console.

client.chatTemplates

Gerencia modelos de mensagem (inclui WABA/WhatsApp Business).

| Método | Descrição | |--------|-----------| | list(params?) | Lista modelos da integração atual | | getById(id, params?) | Retorna modelo por ID | | create(items) | Cria modelos | | update(items) | Atualiza modelos em lote | | submitForReview(id) | Envia modelo WABA para moderação Meta | | updateReviewStatus(id, reviewId, payload) | Atualiza status de revisão (approved, paused, rejected) | | delete(items) | Remove modelos em lote | | deleteOne(id) | Remove um único modelo |

Parâmetros with disponíveis: 'reviews' — inclui review_status, is_on_review e _embedded.reviews

Filtros disponíveis: filter_external_id

⚠️ Validação local: A SDK emite aviso ao tentar atualizar modelos do tipo waba — eles só podem ser editados quando estão em estado draft.

// Criar modelo WABA (WhatsApp Business)
await client.chatTemplates.create({
  name: 'confirmacao_consulta',
  content: 'Olá {{1}}, sua consulta está confirmada para {{2}}.',
  type: 'waba',
  waba_category: 'UTILITY',
  waba_language: 'pt_BR',
  waba_examples: { '1': 'João', '2': '10/06 às 14h' },
});

// Enviar para revisão da Meta
const { _embedded } = await client.chatTemplates.submitForReview(templateId);
console.log(_embedded?.reviews?.[0].status); // "review"

client.webhooks

| Método | Descrição | |--------|-----------| | list(params?) | Lista webhooks registrados | | create(payload) | Cria um webhook | | delete(payload) | Remove um webhook pela URL (destination) |

Filtros disponíveis: filter_destination

⚠️ A exclusão de webhook não usa ID — usa a URL de destino (destination). Isso é um comportamento intencional da API Kommo.

await client.webhooks.create({
  destination: 'https://meuservidor.com/kommo-webhook',
  settings: ['add_lead', 'update_lead', 'add_contact'],
  sort: 10,
});

await client.webhooks.delete({
  destination: 'https://meuservidor.com/kommo-webhook',
});

Eventos conhecidos (settings): add_lead, update_lead, delete_lead, restore_lead, add_contact, update_contact, delete_contact, add_company, update_company, add_task, update_task, delete_task, entre outros.

client.files

A Files API é dividida em três sub-módulos: service, entities e links.

client.files.service — CDN de arquivos (/v1.0/files)

| Método | Descrição | |--------|-----------| | getByUuid(fileUuid) | Retorna arquivo por UUID (ou null se não encontrado) | | list(params?) | Lista arquivos com filtros avançados | | createUploadSession(payload) | Abre uma sessão de upload multipart | | uploadPart(sessionToken, filePart) | Envia parte binária do arquivo | | update(fileUuid, payload) | Renomeia arquivo ou define nova versão ativa | | delete(items) | Remove arquivos em lote | | restore(items) | Restaura arquivos removidos | | listVersions(fileUuid) | Lista versões de um arquivo |

Filtros de listagem disponíveis:

| Parâmetro | Tipo | Descrição | |-----------|------|-----------| | filter_uuid | string[] | Por UUID | | filter_name | string | Por nome | | filter_extensions | string[] | Por extensão | | filter_term | string | Busca textual | | filter_source_id | number | Por fonte | | filter_deleted | boolean | Incluir/excluir deletados | | filter_size_unit / _from / _to | number | Por tamanho | | filter_date_type | 'created_at' \| 'updated_at' | Tipo de data | | filter_date_preset | string | Preset de data (day, week, month, year, last_3_days, etc.) | | filter_date_from / _to | number | Intervalo de datas (Unix) | | filter_created_by / filter_updated_by | number[] | Por usuário (-1 = cliente, 0 = robô) |

⚠️ Validação local: update() lança erro se name e version_uuid forem informados simultaneamente — a API não permite os dois juntos.

// Fluxo completo de upload
const session = await client.files.service.createUploadSession({
  file_name: 'contrato.pdf',
  file_size: buffer.byteLength,
  content_type: 'application/pdf',
});

const sessionToken = (session as any).upload_url?.split('/').pop();

await client.files.service.uploadPart(sessionToken, buffer);

client.files.entities — Anexos em entidades (/api/v4)

| Método | Descrição | |--------|-----------| | listAttachedToEntity(entity, entityId, params?) | Lista arquivos anexados | | attachToEntity(entity, entityId, items) | Anexa arquivos | | detachFromEntity(entity, entityId, items) | Desanexa arquivos |

Entidades suportadas: leads, contacts, companies

client.files.links — Vínculos reversos de arquivo

| Método | Descrição | |--------|-----------| | listLinkedEntities(fileUuid) | Lista as entidades associadas a um arquivo |

🏗️ Arquitetura Interna

| Mecanismo | Descrição | |-----------|-----------| | Raw Body | Rotas com RAW_BODY na Kommo são automaticamente envelopadas como array pelo SDK | | Query String | Usa qs com arrayFormat: 'brackets' — compatível com o backend da Kommo | | 204 → null/void | Respostas 204 No Content são normalizadas para null ou arrays vazios | | Pre-flight checks | Validações locais antes da requisição HTTP para evitar erros 4xx desnecessários | | Normalização PT→EN | Entidades em português (contatos, empresas) são automaticamente normalizadas para o inglês usado na API |

📄 Licença

MIT — livre para uso, modificação e distribuição.