Autenticação e convenções

Header de autenticação

Envie a chave no header Authorization, como Bearer token, em toda requisição:

Authorization: Bearer lsk_api_...

curl https://api.plus.qa.leadsim.com.br/companie/funnel \
  -H "Authorization: Bearer lsk_api_SUA_CHAVE"

Não há login, cookie nem renovação de token: a chave vale até ser revogada, vencer ou ser substituída. Veja Sua chave de API.

Permissões herdadas

A chave tem as mesmas permissões do usuário dono nas telas do LeadSim:

• Rotas de módulos que o perfil do dono não enxerga falham do mesmo jeito que nas telas.
• Em funil restrito, listagens de oportunidades trazem só as do dono da chave.
• Registros criados pela API (contatos, oportunidades, propostas, contratos) ficam em nome do dono.
• A empresa vem sempre da chave. Nenhuma rota pede o id da empresa: listagens como GET /companie/funnel já respondem com os dados da empresa do dono da chave.

Erros de autenticação

Respondidos pelo middleware de autenticação em texto puro (text/plain), só com o código:

Status	Código	Significado
401	no_token_provided	Header Authorization ausente.
401	error_api_key_invalid	Chave inexistente ou digitada errada.
401	error_api_key_revoked	Chave revogada (pelo dono, pelo administrador ou por uma chave nova).
401	error_api_key_expired	Chave vencida. Gere uma nova.
401	error_api_key_user_inactive	O usuário dono da chave foi desativado.
403	error_api_key_no_access	O perfil do dono da chave não tem mais o menu Integração API.
403	error_api_key_companie_inactive	A empresa não está ativa.
403	error_api_key_forbidden_route	Rota fora desta documentação. A chave de API só acessa as rotas listadas aqui.
429	error_api_key_rate_limited	Limite excedido: 300 requisições por minuto por chave e 1.500 por empresa. Veja os headers RateLimit-*.

O que fazer em cada caso está em Problemas comuns.

Limite de requisições

Limite	Janela	Chave do contador
300 requisições	1 minuto	por chave de API
1.500 requisições	1 minuto	por empresa (soma de todas as chaves)

Toda resposta traz os headers padrão de rate limit:

Header	Conteúdo
RateLimit-Limit	Teto da janela atual.
RateLimit-Remaining	Quantas requisições ainda cabem na janela.
RateLimit-Reset	Segundos até a janela zerar.

Ao estourar, a resposta é 429 com o texto error_api_key_rate_limited e o header Retry-After. Espere o tempo indicado antes de tentar de novo; não insista em loop. Cargas grandes (importação, sincronização inicial) devem ser espaçadas para ficar abaixo do limite.

Rotas permitidas

A chave de API acessa só as rotas da Referência de rotas. O LeadSim tem outras rotas, usadas pelas telas, mas elas não fazem parte da API de integração: com a chave, respondem 403 error_api_key_forbidden_route. Isso vale também para sessão, administração, MCP, gestão das próprias chaves e compras de crédito.

Convenções

Datas e horários

• Datas em YYYY-MM-DD, no horário de Brasília. Exemplo: 2026-10-23.
• Datas com hora vêm em ISO 8601 com o horário de Brasília e sufixo Z. Trate o valor como horário de Brasília, não como UTC.

Valores

Valores decimais vêm como string, por exemplo "150.00". Converta no seu lado antes de somar.

Listagens com filtro (filterAdvanced)

As listagens com filtro são POST .../filterAdvanced/.... O período vai na URL e os demais filtros no corpo:

POST /companie/financial/filterAdvanced/:filter/:date_start/:date_end

• filter: all, today, yesterday, this_week, last_week, this_month, last_month, next_month, last_30_days ou other_period.
• date_start e date_end (YYYY-MM-DD) só são lidos com other_period. Com os demais valores de filter, repita qualquer data válida ou omita os dois segmentos quando a rota permitir.
• Alguns módulos (Propostas, Contratos) recebem o período no corpo em vez da URL. Cada rota diz onde.
• Vários corpos de filterAdvanced exigem os arrays de filtro sempre presentes, nem que vazios ([]). A referência de cada rota marca quais; sem eles a rota responde 500.

Paginação

Listagens paginadas recebem skip (registros a pular) e take (tamanho da página), na URL ou no corpo conforme a rota. A resposta das rotas filterAdvanced é:

{ "data": [ ... ], "total": 137 }

total é o total do filtro, não da página. Algumas listagens simples (GET) devolvem um array direto, sem total; a referência indica.

Erros de validação e de negócio

Status	Formato	Quando
400	JSON ValidationError: statusCode, error, message e validation com os campos recusados	Corpo ou parâmetro inválido (tipo errado, campo obrigatório ausente, enum fora da lista).
404 / 409	JSON GenericError (status_code, message, error) ou só o código em texto	Regra de negócio: registro inexistente na empresa, duplicidade, status que não permite a operação.

Os códigos de negócio de cada rota (por exemplo error_person_id_not_exist) estão na tabela Respostas da rota, na referência.

Teste primeiro no Swagger

O Swagger mostra o schema exato de cada corpo e devolve o erro de validação completo. É o jeito mais rápido de acertar um filterAdvanced.