kommo-aiatende-api 1.0.1 → 1.2.0

package/README.md

@@ -1,7 +1,8 @@
-# Kommo API SDK (V4) 🚀
+# kommo-aiatende-api
 
-SDK moderno, resiliente e **totalmente tipado** em TypeScript para a API V4 da [Kommo CRM](https://kommo.com).
+SDK não oficial, moderno e **totalmente tipado** em TypeScript para a API V4 da [Kommo CRM](https://kommo.com). 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
 
@@ -13,124 +14,623 @@ yarn add kommo-aiatende-api
 pnpm add kommo-aiatende-api
 ```
 
-## ✨ Funcionalidades Mapeadas
+---
 
-Esta biblioteca foi desenhada com alto nível de rigor às complexidades da documentação da Kommo, encapsulando vulnerabilidades e garantindo auto-complete puro via Typescript (IntelliSense) em centenas de propriedades:
+## 🚀 Inicialização
 
-*   **Entidades Base:** `leads`, `contacts`, `companies`
-*   **Caixa de Entrada (Unsorted):** Aceitar, recusar e vincular dados do pipeline.
-*   **Funis (Pipelines & Status):** Configuração estrutural do CRM.
-*   **Campos Personalizados (Custom Fields & Groups):** Inclusão de tipagem complexa para metadados invisíveis.
-*   **Usuários e Funções (Users & Roles):** Leitura de Rights Limit.
-*   **Notas e Tarefas (Notes & Tasks):** Com resolução inteligente do campo result.
-*   **Eventos (Events):** Logs estruturados para ValueType Polymorphism.
-*   **Listas (Catalogs & Elements)**.
-*   **Tags:** Operações de batch patching e validações de Hex colors.
-*   **Vínculos (Links):** Proteções Pre-flight em filtros essenciais.
-*   **Salesbots & Templates (Waba):** Controle rigoroso de disparos com validações Max Length Limits.
-*   **Integrações Externas:** Fontes (`sources`), Webhooks e Botões de Chat Web.
+```typescript
+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.
+
+---
 
-## 🚀 Configuração Básica
+## 🛡️ Tratamento de Erros
 
-Inicializando e injetando o cliente em sua aplicação Node.js:
+Todos os erros HTTP são convertidos em `KommoApiError`:
 
 ```typescript
-import { KommoClient } from 'kommo-aiatende-api';
+import { KommoApiError } from 'kommo-aiatende-api';
 
-const client = new KommoClient({
-  domain: 'meudominio', // Não inclua ".kommo.com", apenas o subdomínio!
-  accessToken: 'SEU_BEARER_TOKEN_AQUI'
+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) |
+
+```typescript
+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);
 ```
 
-*Nota: Todos os métodos assumem que seus tokens são válidos. Você deve implementar o fluxo OAuth2.0 separadamente para emitir e reciclar seus tokens.*
+---
+
+### `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 |
+
+```typescript
+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`
 
 ---
 
-## 📖 Exemplos Rápidos de Uso
+### `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 |
 
-### 1. Criando Entidades com Proteção Typada
 ```typescript
-import { KommoClient } from 'kommo-aiatende-api';
+// Aceitar um lead não classificado
+await client.unsorted.accept('UID_DO_LEAD', {
+  user_id: 123,
+  status_id: 456,
+});
 
-const client = new KommoClient({ domain: 'meudominio', accessToken: 'TOKEN' });
-
-async function criarLead() {
-  const result = await client.leads.create({
-    name: 'Novo Negócio Estratégico',
-    price: 15400,
-    tags_to_add: [
-        { name: 'VIP' }
-    ]
-  });
-  
-  console.log('Lead criado com sucesso: ', result._embedded?.leads?.[0].id);
-}
+// Vincular a um lead existente
+await client.unsorted.link('UID_DO_LEAD', {
+  link: {
+    entity_id: 9999,
+    entity_type: 'leads',
+  },
+});
 ```
 
-### 2. Vínculos Avançados (Links)
+---
+
+### `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.
 
-Conecte um contato diretamente ao seu Lead recém-criado em Lote (Batch).
 ```typescript
-await client.links.link('leads', 15591, [
-    {
-       to_entity_type: 'contacts',
-       to_entity_id: 11069775,
-       metadata: {
-          is_main: true // O SDK normalizará as ambiguidades da API!
-       }
-    }
-]);
+// 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 |
+
+```typescript
+// Listar elementos de um catálogo com busca textual
+const { _embedded } = await client.catalogs.listElements(42, {
+  query: 'Produto X',
+  limit: 20,
+});
 ```
 
-### 3. Executando um Salesbot com Barreiras Físicas
+---
+
+### `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.
 
-Esqueça o Erro "403 Limit Exceeded" da Kommo por não conhecer os limites. A própria SDK bloqueia antes do tráfego:
 ```typescript
-await client.salesbots.runMany([
-    // ... se passar de 100 itens ...
-    // Throws: "A API da Kommo limita o 'runMany' a no máximo 100 salesbots por requisição."
+// 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' }] },
+});
 ```
 
-### 4. Gestão do Funil (Pipelines)
+---
+
+### `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`.
+
 ```typescript
-const funis = await client.pipelines.list();
+// 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' },
+});
 
-const funilAtivo = funis._embedded?.pipelines?.find(p => p.is_main);
-console.log('Funil Principal: ', funilAtivo?.name);
+// Enviar para revisão da Meta
+const { _embedded } = await client.chatTemplates.submitForReview(templateId);
+console.log(_embedded?.reviews?.[0].status); // "review"
 ```
 
 ---
 
-## 🛡️ Tratamento de Erros Moderno e Intuitivo
+### `client.webhooks`
 
-Qualquer rota falha lançará a classe `KommoApiError`. Ela empacota o padrão nativo de `application/problem+json` num wrapper explícito:
+| 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.
 
 ```typescript
-import { KommoApiError } from 'kommo-aiatende-api/errors';
+await client.webhooks.create({
+  destination: 'https://meuservidor.com/kommo-webhook',
+  settings: ['add_lead', 'update_lead', 'add_contact'],
+  sort: 10,
+});
 
-try {
-  await client.leads.getById(99999999);
-} catch (error) {
-  if (error instanceof KommoApiError) {
-    console.error('Código HTTP:', error.status); // ex: 404
-    console.error('Título da Kommo:', error.title);
-    console.error('Detalhe Técnico:', error.detail);
-    
-    // Payload brutal devolvido pela requisição (quando disponível)
-    console.log(error.raw);
-  }
-}
+await client.webhooks.delete({
+  destination: 'https://meuservidor.com/kommo-webhook',
+});
 ```
 
-## 🏗️ Padrões Internos (Architecture)
-A lib adota dois estilos de serialização para proteger suas chamadas:
-1. **Raw Body Conversions:** Rotas da Kommo v4 exigem arrays brutos (`[]`) misturados a requests sem aninhamento de object. O SDK mapeia se você enviou Arrays ou Singleton e encapsula conforme o exigido na Doc.
-2. **Query String Normalization:** Usamos o `qs` com a instrução `{ arrayFormat: 'brackets' }` para evitar que seus arrays nos filtros de `GET` quebrem a formatação em backend na Rússia.
+**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.
+
+```typescript
+// 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
-Licenciado sob a Licença MIT. Sinta-se livre para ramificar e customizar seu repositório local.
+
+MIT — livre para uso, modificação e distribuição.