> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinglog.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> URL base, autenticação, formato de resposta, códigos de status e como ler cada operação.

Esta seção documenta a API que a sua empresa chama na KingLog. Tarefa, projeto, funil, ticket e relatório usam as mesmas regras de autenticação, resposta e erro descritas aqui. Leia esta página uma vez. Ela evita a maior parte dos erros de integração.

> [card] [Autenticação](https://docs.kinglog.com.br/pages/authentication.md)
>
> JWT da conta, empresa e usuário.

> [card] [Ambiente de testes](https://docs.kinglog.com.br/pages/devmode.md)
>
> A mesma API, na URL de homologação.

> [card] [Webhooks](https://docs.kinglog.com.br/pages/webhooks/index.md)
>
> 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.

```text theme={null}
https://SUA_API
```

Uma chamada fica assim:

```text theme={null}
POST https://SUA_API/called/create
Authorization: Bearer SEU_JWT
```

## Autenticação

Quase toda rota exige o JWT de um usuário da empresa:

```text theme={null}
Authorization: Bearer SEU_JWT
```

O token diz quem está chamando. Onde o caminho ou o corpo pede `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](https://docs.kinglog.com.br/pages/webhooks/canais.md).

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](https://docs.kinglog.com.br/pages/authentication.md).

## Formato de resposta

Sucesso:

```json theme={null}
{
  "success": true,
  "data": {},
  "code": "SUCCESS"
}
```

Erro de regra de negócio, vindo da operação:

```json theme={null}
{
  "success": false,
  "status": 400,
  "message": "Mensagem descritiva do erro",
  "code": "CODIGO",
  "errors": []
}
```

Validação de corpo, caminho ou query, antes da operação rodar:

```json theme={null}
{
  "success": false,
  "error": {},
  "code": "CODIGO_OU_AUSENTE"
}
```

`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.

> [!NOTE]
>
> 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

| Código | Quando acontece |
| - | - |
| `200` | A operação concluiu e `data` vem preenchido |
| `204` | A chamada pública não tinha conteúdo para devolver |
| `400` | Corpo ou combinação de campos recusada. Na consulta, o código é `QUERY_INVALID` |
| `401` | JWT ausente, inválido ou chave `kl_live_` revogada |
| `403` | A pessoa, ou a chave restrita, não pode esse recurso. Na consulta, `QUERY_ENTITY_FORBIDDEN` |
| `404` | Registro, rota ou métrica inexistente |
| `409` | O estado atual não aceita a mudança |
| `422` | A consulta passou da complexidade permitida, código `QUERY_TOO_COMPLEX` |
| `429` | A consulta passou do limite de uso, código `QUERY_RATE_LIMITED` |
| `500` | Falha interna |
| `504` | A consulta passou do tempo, código `QUERY_TIMEOUT` |

## 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 com `grants`, 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](https://docs.kinglog.com.br/pages/start/chaves).

## Empresa e usuário

A maior parte das rotas recebe `companyId` 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.

| Tipo de lista | Como pagina |
| - | - |
| Busca na empresa | Cursor. `limit` de 1 a 100. A página seguinte usa o `cursor` devolvido |
| Consulta dinâmica | `offset` ou `cursor`, com `limit` de 1 a 500 |
| Listas do produto | Filtros no corpo ou no caminho, descritos na página da operação |

A busca está em [Busca global](https://docs.kinglog.com.br/pages/reference/search/search-global.md). A consulta está em [Consultar dados](https://docs.kinglog.com.br/pages/guides/consultar-dados.md).

## 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

O identificador, como `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](https://docs.kinglog.com.br/pages/reference/mapa.md).

## Erros mais comuns

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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

> [card] [Teste na URL de homologação](https://docs.kinglog.com.br/pages/devmode.md)
>
> Mesmos caminhos. Outra URL, outro usuário, outra chave.

> [card] Guarde o JWT fora do código
>
> Variável de ambiente ou cofre. O mesmo vale para `kl_live_`.

> [card] [Leia a operação antes de montar o corpo](https://docs.kinglog.com.br/pages/reference/mapa.md)
>
> O corpo de criar tarefa não é o de criar lead.

> [card] [Confirme o id e só então grave](https://docs.kinglog.com.br/pages/reference/search/search-global.md)
>
> Busca e leitura devolvem o id que a escrita aceita.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.