Kommo API: Guia Completo para Desenvolvedores

Visão geral da API do Kommo

A API do Kommo CRM é uma API RESTful que permite integrar e automatizar praticamente tudo que você faz na interface web do Kommo. Desde criar leads e contatos até enviar mensagens, mover cards no pipeline e configurar webhooks — tudo está disponível via API.

A API é bem documentada pela equipe do Kommo, mas a documentação oficial pode ser complexa para quem está começando. Neste guia, vamos simplificar os conceitos essenciais e fornecer exemplos práticos para que você comece a integrar rapidamente. Se você não é desenvolvedor, pode usar ferramentas como n8n para fazer integrações sem código.

Antes de mergulhar na API, recomendamos entender a estrutura do Kommo lendo nosso guia completo do Kommo CRM.

Autenticação: OAuth 2.0

A API do Kommo utiliza OAuth 2.0 para autenticação. Isso significa que você precisa registrar uma integração no Kommo e obter tokens de acesso. Existem dois tipos de integrações:

Integrações privadas (mais simples)

Ideal para uso interno, quando você precisa integrar apenas a sua conta Kommo. O processo é:

• No Kommo, vá em Configurações e depois em Integrações e depois Criar integração.
• Marque como "Integração privada".
• Defina as permissões necessárias (leads, contatos, pipeline, etc.).
• Copie o código de autorização que é gerado automaticamente.
• Troque o código de autorização por um access token e refresh token fazendo um POST para o endpoint de token.

Exemplo de request para obter o token:

POST https://[seu-subdominio].kommo.com/oauth2/access_token

• client_id: ID da sua integração
• client_secret: Secret da integração
• grant_type: authorization_code
• code: Código de autorização
• redirect_uri: URL de redirecionamento configurada

Integrações públicas

Para aplicações que serão usadas por múltiplas contas Kommo (como um SaaS que integra com Kommo). Seguem o fluxo completo de OAuth 2.0 com autorização do usuário.

Refresh tokens

Os access tokens do Kommo expiram a cada 24 horas. Você precisa implementar a lógica de refresh automático usando o refresh token. Quando o access token expira, faça um POST com grant_type "refresh_token" para obter um novo par de tokens.

Endpoints principais

Leads (Negócios)

O endpoint de leads é o mais usado na API do Kommo. Leads representam os cards no pipeline.

• GET /api/v4/leads — Listar leads. Suporta filtros por pipeline, status, responsável, tags e campos customizados. Paginação com limit e page.
• GET /api/v4/leads/{id} — Obter detalhes de um lead específico. Use o parâmetro "with" para incluir contatos, catálogo e campos customizados.
• POST /api/v4/leads — Criar novos leads. Envie um array de objetos com name, price, status_id (etapa do pipeline), pipeline_id e custom_fields_values.
• PATCH /api/v4/leads/{id} — Atualizar um lead existente. Envie apenas os campos que deseja alterar.

Contatos

• GET /api/v4/contacts — Listar contatos com filtros.
• POST /api/v4/contacts — Criar contatos. Inclua name, custom_fields_values (telefone, e-mail, etc.).
• PATCH /api/v4/contacts/{id} — Atualizar contatos.

Obs: Telefone e e-mail são campos customizados padrão no Kommo, não campos nativos. Você precisa usar os IDs corretos dos campos.

Pipeline e Status

• GET /api/v4/leads/pipelines — Listar todos os pipelines e suas etapas (statuses).
• GET /api/v4/leads/pipelines/{pipeline_id}/statuses — Listar etapas de um pipeline específico.

Use esses endpoints para obter os IDs de pipelines e etapas que você precisará ao criar ou mover leads.

Tarefas

• GET /api/v4/tasks — Listar tarefas.
• POST /api/v4/tasks — Criar tarefas vinculadas a leads ou contatos.
• PATCH /api/v4/tasks/{id} — Atualizar tarefas (marcar como completa, por exemplo).

Notas

• POST /api/v4/leads/{id}/notes — Adicionar notas a um lead. Tipos: common (texto), call (ligação), service_message (mensagem do sistema).

Tags

• GET /api/v4/leads/tags — Listar tags disponíveis.
• Tags são adicionadas via PATCH no lead, incluindo o array _embedded.tags.

Webhooks

Os webhooks do Kommo notificam sua aplicação em tempo real quando eventos acontecem no CRM. Isso elimina a necessidade de polling constante.

Eventos disponíveis

• leads — Criação, atualização, exclusão e mudança de status de leads.
• contacts — Criação, atualização e exclusão de contatos.
• tasks — Criação, conclusão e exclusão de tarefas.
• notes — Adição de notas.
• pipeline — Mudanças na estrutura do pipeline.

Configurando webhooks

Vá em Configurações e depois Integrações e depois sua integração e depois Webhooks. Adicione a URL de destino e selecione os eventos desejados. O Kommo enviará um POST para sua URL com o payload do evento.

Dica: Use uma ferramenta como Webhook.site ou RequestBin durante o desenvolvimento para inspecionar os payloads que o Kommo envia.

Limites de rate (rate limiting)

A API do Kommo tem limites de requisições que variam por plano:

• Base: 7 requisições por segundo
• Avançado: 7 requisições por segundo
• Enterprise: 15 requisições por segundo

Além disso, existe um limite de 7.000 requisições por minuto. Se você exceder o limite, receberá um erro 429 (Too Many Requests). Implemente retry com backoff exponencial no seu código.

Dicas para otimizar requests

• Use batch operations — A API permite criar, atualizar e excluir múltiplos registros em uma única requisição (até 250 itens por batch).
• Filtre no servidor — Use os parâmetros de filtro da API em vez de trazer todos os dados e filtrar localmente.
• Cache tokens — Não solicite novos tokens a cada requisição. Armazene e reutilize até expirar.
• Use webhooks — Em vez de fazer polling, use webhooks para ser notificado de mudanças.

Campos customizados via API

Trabalhar com campos customizados na API do Kommo pode ser confuso no início. Cada campo tem um ID numérico único, e você precisa desses IDs para ler e escrever valores.

Para obter os IDs dos campos customizados:

• GET /api/v4/leads/custom_fields — Lista campos de leads.
• GET /api/v4/contacts/custom_fields — Lista campos de contatos.

Para atualizar um campo customizado em um lead, envie no PATCH:

custom_fields_values com um array contendo field_id e values (array de objetos com value).

Integrações populares com a API do Kommo

As integrações mais comuns que desenvolvedores criam com a API incluem:

• Integração com sites — Formulários web que criam leads automaticamente no Kommo.
• Integração com e-commerce — Sincronizar pedidos, carrinhos abandonados e clientes. Veja mais em Kommo para E-commerce.
• Integração com ERPs — Sincronizar dados financeiros e de estoque.
• Dashboards customizados — Extrair dados do Kommo para dashboards personalizados.
• Chatbots com IA — Integrar modelos de linguagem que leem e escrevem dados no Kommo. Confira nosso guia de IA conversacional no Kommo.

Ferramentas para desenvolvedores

• Postman Collection — O Kommo oferece uma coleção Postman pronta para testes.
• n8n — Para automações sem código que consomem a API. Veja nosso guia de n8n + Kommo.
• SDKs da comunidade — Existem SDKs não oficiais em Python, Node.js e PHP mantidos pela comunidade.

Precisa de integrações customizadas?

A equipe de desenvolvimento da Metrik cria integrações customizadas com a API do Kommo para empresas de todos os portes. Como Top 5% Kommo Brasil, conhecemos a API em profundidade e já construímos dezenas de integrações. Conheça nossos planos e tenha integrações profissionais funcionando no seu CRM.