Autenticação
JWT da conta, empresa e usuário.
Ambiente de testes
A mesma API, na URL de homologação.
Webhooks
Entrar um lead e receber os canais.
URL base
A KingLog informa a URL do seu ambiente. Teste e produção são endereços diferentes. Os caminhos desta referência são os mesmos nos dois.Autenticação
Quase toda rota exige o JWT de um usuário da empresa:companyId e userId, use a empresa e o usuário desse token. Os dois precisam ser da mesma conta.
Sem token, ou com token inválido, a resposta é 401. Sem permissão para o recurso, 403.
GET /health não pede token. As entradas de WhatsApp, Meta, Google e do bot de reunião também não usam o JWT da pessoa. Elas estão em Canais.
A chave kl_live_ não substitui o JWT na integração do seu sistema. Ela serve ao assistente no Cursor e no Claude. Quem chama a API direto usa o JWT. Os dois estão em Autenticação.
Formato de resposta
Sucesso:error traz o detalhe do campo recusado. Quando a validação define um código, ele vem em code para o seu sistema tratar sem depender do texto.
Leia
success antes de usar data. Em falha de validação a mensagem fica em error. Nas outras falhas, fica em message, com o HTTP em status.Códigos de status
Permissões
O que a chamada pode fazer é o que aquele usuário pode fazer na empresa. Administrador enxerga o conjunto da conta. Os demais ficam no recorte das permissões. A chave do assistente, quando criada comgrants, faz só esse conjunto, e nunca uma permissão que a conta não tem. Sem grants, ela acompanha a pessoa. O detalhe está em Chaves de API.
Empresa e usuário
A maior parte das rotas recebecompanyId e userId no caminho ou no corpo. Eles identificam a conta, não um filtro opcional. Trocar o id no corpo não muda a empresa do token.
Datas de tarefa vão como YYYY-MM-DD em date_start e date_end. date_sprint pode ocupar o lugar das duas. Relatório salvo usa período Daily, Weekly, Monthly, Quarterly ou Yearly.
Listas
Não existe um único parâmetro de página para a API inteira. Cada operação descreve o próprio filtro.
A busca está em Busca global. A consulta está em Consultar dados.
Como ler uma operação
Cada página da barra lateral traz:- o método e o caminho, prontos para prefixar com a URL base
- o efeito: leitura, escrita ou exclusão
- o que o corpo, o caminho ou a query exigem, quando isso está definido
tasks.create, é o mesmo contrato para o assistente. Na integração HTTP você usa método e caminho. No Cursor ou no Claude, o assistente usa o identificador.
O mapa do que cada área permite está em O que a API cobre.
Erros mais comuns
400 — os campos foram enviados e a chamada volta inválida
400 — os campos foram enviados e a chamada volta inválida
Confira o tipo. Cliente em tarefa é o uuid, não o nome. Datas são
YYYY-MM-DD. Na consulta, QUERY_INVALID lista os campos aceitos: ajuste e repita.401 — o token parece certo
401 — o token parece certo
O header é
Authorization: Bearer SEU_JWT, com um espaço, sem aspas em volta do token. JWT de teste não vale na URL de produção, e o contrário também.403 — a pessoa está logada e mesmo assim não passa
403 — a pessoa está logada e mesmo assim não passa
A conta não tem essa permissão, ou a chave
kl_live_ foi criada com um conjunto menor. Permissão de chave não se edita: revogue e crie outra.404 — o id não abre o registro
404 — o id não abre o registro
O id é o que a listagem ou a busca devolveu. Título e código visual não substituem o id, salvo onde a página da operação diz que aceita código.
5xx — a KingLog falhou do lado dela
5xx — a KingLog falhou do lado dela
Espere e repita a leitura. Em criação, confira antes se o registro já nasceu, para não duplicar.
Dicas
Teste na URL de homologação
Mesmos caminhos. Outra URL, outro usuário, outra chave.
Guarde o JWT fora do código
Variável de ambiente ou cofre. O mesmo vale para
kl_live_.Leia a operação antes de montar o corpo
O corpo de criar tarefa não é o de criar lead.
Confirme o id e só então grave
Busca e leitura devolvem o id que a escrita aceita.