A API de integração deixa o sistema de um parceiro (site, CRM, sistema de gestão, contador ou uma inteligência artificial) consultar os dados da sua loja, sempre atualizados, sem planilha nem cópia manual. Cada parceiro recebe uma chave própria, com as permissões que a loja escolher, e a loja pode desativar a chave quando quiser.
Gerar a chave
Quem gera: o administrador da loja e os tipos de usuário que ele liberar (veja Quem pode gerar chave).
- No menu, vá em Configurações > Integrações > API de integração. Qualquer funcionário abre essa tela, mas só gera chave quem tem permissão; para os outros, o formulário aparece bloqueado com o aviso para pedir ao administrador.
- Em Gerar nova chave, escreva para quem é a chave (ex.: "Site da agência X" ou "Assistente de IA").
- Em O que ela pode acessar, marque Estoque publicado (para site, portal ou assistente de vendas) e/ou Dados de gestão (para quem cuida da gestão da loja: contador, consultor, sistema ou IA de gestão). Toda chave também pode mandar interessados para a sua Gestão de Leads (site, landing page, robô de WhatsApp): não precisa marcar nada.
- Escolha a Validade (90 dias, 6 meses ou 1 ano).
- Leia o Termo de uso e proteção de dados (LGPD) e marque o aceite. Ficam registrados a versão do termo, a data, quem aceitou e o IP, e o administrador recebe por e-mail o registro do aceite com o texto do termo.
- Digite a sua senha do painel e clique em Gerar chave.
- Clique em Copiar e entregue a chave ao técnico do parceiro. Ela aparece uma única vez: nem o suporte ItCar consegue mostrar de novo. Se perder, desative e gere outra.
Cada loja pode ter até 5 chaves ativas ao mesmo tempo. Com Estoque publicado, a chave só enxerga o que o seu site já mostra. Com Dados de gestão, ela vê também placa, chassi, Renavam, observações internas, valores de compra e venda, custos, contas e o cadastro completo de clientes e fornecedores (nome, CPF/CNPJ, RG, nascimento, telefones, e-mail e endereço). Senhas e dados bancários nunca saem pela API. Toda chave pode criar leads novos na Gestão de Leads, mas não lê, não altera e não apaga os leads que já existem.
Quem pode gerar chave
- O administrador sempre pode, com qualquer permissão.
- Para liberar outro tipo de usuário (gerente, marketing...), o administrador vai em Configurações > Tipos de Usuários, edita o tipo e marca Pode gerar chave da API de integração. Só o administrador vê e muda essa opção.
- Quem não é administrador gera chave só de Estoque publicado e de Meus leads e minhas vendas (os Dados de gestão da loja inteira só o administrador libera) e vê e desativa só as chaves que ele mesmo gerou. O administrador vê todas.
- Meus leads e minhas vendas é para o vendedor: a chave vê só os leads dele (com o histórico e o contato do cliente) e os números de venda dele (quantidade, faturamento, ticket médio e conversão de leads). Nunca vê os leads e as vendas de outro vendedor, nem lucro, custos, estoque ou contas da loja. O usuário precisa estar ligado a um vendedor no cadastro de usuários; sem isso, a opção aparece bloqueada.
- A chave só funciona enquanto quem a gerou continuar com essa permissão. Se a pessoa mudar de tipo de usuário, for desativada ou sair, ou se o administrador desmarcar a opção do tipo dela, as chaves param (aparecem como Parada) e é preciso gerar novas. O acesso temporário da Equipe Suporte também conta: chave gerada por ele para quando o acesso vence.
Desativar uma chave e acompanhar os acessos
- Na lista Chaves da sua loja, clique em Desativar. O sistema que usava a chave perde o acesso na hora.
- Em Últimos acessos aparecem as chamadas mais recentes: quando, de qual IP, o que foi pedido e se deu certo ou foi recusado (chave inválida, limite por minuto etc.).
Conversar com os dados da loja no ChatGPT ou no Claude
A ItCar tem um conector pronto (padrão MCP) para assistentes de inteligência artificial. Depois de conectar, é só perguntar, do seu jeito: "quanto lucrei em setembro?", "quais carros estão há mais tempo no estoque?", "o que vence esta semana?", "tem algum SUV até 80 mil?", "cadastra um lead para a Maria, telefone ...".
- Gere uma chave nesta tela. Para perguntas sobre lucro, compras, vendas e contas, marque Dados de gestão.
- No Claude: vá em Configurações > Conectores, clique em Adicionar conector personalizado, dê um nome (ex.: ItCar) e cole o endereço
https://api.itcar.com.br/mcp. - No ChatGPT: em Configurações > Apps e conectores, ative o modo de desenvolvedor nas configurações avançadas (precisa de um plano que permita conectores personalizados), crie um conector com o endereço
https://api.itcar.com.br/mcpe escolha autenticação OAuth. - Clique em Conectar. Abre uma tela da ItCar pedindo a chave: cole a chave e clique em Conectar. Você volta para o assistente já conectado.
- O assistente vê só o que a chave libera e não recebe a chave em si. Desativar a chave no painel desconecta o assistente na hora.
- O que o assistente consegue fazer: consultar o estoque publicado, ver o resumo da loja, listar veículos com compra, venda e resultado, abrir a ficha completa de um veículo, consultar contas a pagar e a receber, ver os leads com o histórico de contatos, trazer indicadores prontos (margem, ranking de vendedores, carros parados, conversão de leads, caixa das próximas semanas) e cadastrar leads. Ele não altera nem apaga nada. Leads e indicadores precisam de uma chave com Dados de gestão.
- Para o técnico: o servidor MCP usa o transporte Streamable HTTP em
https://api.itcar.com.br/mcp, com login OAuth 2.1 (registro dinâmico de cliente e PKCE S256). Ferramentas como Claude Code, n8n e outros clientes que aceitam cabeçalho também podem mandar a chave direto emAuthorization: Bearer.
Para o técnico: como chamar a API
Endereço: https://api.itcar.com.br. A documentação interativa (OpenAPI/Swagger), onde dá para testar com a chave, fica em https://api.itcar.com.br/docs.
Mande a chave no cabeçalho Authorization, sempre por HTTPS. Chave na URL não é aceita.
curl -H "Authorization: Bearer itc_SUA_CHAVE" https://api.itcar.com.br/v1/chave
curl -H "Authorization: Bearer itc_SUA_CHAVE" "https://api.itcar.com.br/v1/veiculos?por_pagina=20&ordenar=-preco"
Rotas disponíveis
GET /v1/status: confere se a API está no ar. Não precisa de chave.POST /mcp: conector MCP para ChatGPT, Claude e outros assistentes (veja acima).GET /v1/chave: tudo sobre a chave em uso: nome, permissões, as rotas que ela libera, se os leads e indicadores vêm filtrados por um vendedor (somente_do_vendedor), os limites de uso e a validade. Bom para testar a conexão.GET /v1/veiculos: lista paginada do estoque publicado no site da loja.GET /v1/veiculos/{id}: um veículo do estoque publicado, com opcionais e fotos.POST /v1/leadseGET /v1/leads/origens: com qualquer chave (veja abaixo).
Com a permissão Dados de gestão:
GET /v1/gestao/resumo: panorama da loja: veículos em estoque e quanto custaram, vendas e resultado do mês, contas a pagar e a receber em aberto e vencidas.GET /v1/gestao/veiculos: todos os veículos (em estoque, reservados, vendidos e cancelados), um por linha, com placa, chassi, Renavam, datas e valores de compra e venda, custos e resultado. Filtros:situacao(em_estoque,reservado,vendido,cancelado),tipo_entrada(proprio,consignado,intermediacao),placa,vendido_deevendido_ate(aaaa-mm-dd). Ordem:ordenarcom-id(padrão),id,-data_vendaoudata_venda.GET /v1/gestao/veiculos/{id}: a ficha completa do veículo (com Renavam e observações internas): compra (de quem, valor, condições e parcelas), venda (para quem, valor, condições, veículos recebidos na troca, financiamento e parcelas), custos, receitas extras, totais e o camporesumo_em_texto, uma frase pronta com o essencial do veículo. A pessoa de quem a loja comprou, a pessoa para quem vendeu e quem reservou vêm com o cadastro completo.GET /v1/gestao/contas: contas a pagar e a receber, por vencimento, com parcela ("3 de 12"), valor total, valor pago, valor em aberto, situação (aberta,vencidaouquitada) e o cadastro completo do cliente ou fornecedor. Filtros:tipo(pagaroureceber),situacao,vencimento_de,vencimento_ateeveiculo_id.situacao=abertatraz também as vencidas.GET /v1/gestao/leads: os leads da Gestão de Leads, com situação, resultado (ganho,perdidoouem_andamento), vendedor, origem, veículo, dados do cliente, próximo contato e última interação. Filtros:situacao(aberto,em_negociacao,finalizado),resultado,vendedor_id,sem_vendedor=true,origem_id,veiculo_id,aberto_deeaberto_ate,contato_atrasado=true. Ordem:-id(padrão),id,proximo_contatoou-abertura.GET /v1/gestao/leads/{id}: um lead com a descrição e todo o histórico de interações (ligações, mensagens, visitas).GET /v1/gestao/indicadores: números prontos. Do período (deeate; padrão: do dia 1 do mês até hoje; no máximo 1 ano): vendas, faturamento, resultado, margem, ticket médio, dias médios para vender, vendas por marca e por vendedor, leads recebidos, ganhos e perdidos, conversão por origem e motivos de perda. De hoje: estoque por idade e os 10 carros mais antigos, leads sem vendedor ou com contato atrasado e o caixa previsto dos próximos 30 dias, semana a semana.
Com a permissão Meus leads e minhas vendas (sem Dados de gestão), as rotas /v1/gestao/leads, /v1/gestao/leads/{id} e /v1/gestao/indicadores respondem só com os dados do vendedor de quem gerou a chave: lead de outro vendedor dá 404, e os indicadores vêm com "escopo": "vendedor", o vendedor e só vendas e leads dele (sem resultado, estoque nem caixa). Com Dados de gestão vem "escopo": "loja".
Nos dados de gestão, a compra e a venda vêm separadas, com códigos próprios (C-1532 e V-1532). Débitos e quitação de financiamento abatidos na compra aparecem nas condições da compra com abate_do_valor: true. Valor que a loja não informou vem null, nunca zero. O resultado segue a mesma conta do painel: venda menos compra, mais receitas extras, menos custos. As listas de gestão também são paginadas com pagina e por_pagina (padrão 50, máximo 100), e as datas vêm em aaaa-mm-dd.
Enviar leads para a Gestão de Leads
Com qualquer chave, o sistema do parceiro manda o interessado direto para a Gestão de Leads da loja:
curl -X POST https://api.itcar.com.br/v1/leads \
-H "Authorization: Bearer itc_SUA_CHAVE" -H "Content-Type: application/json" \
-d '{ "nome": "Maria Silva", "telefone": "(11) 99999-8888", "email": "maria@exemplo.com",
"mensagem": "Ainda está disponível? Aceita troca?", "veiculo_id": 664,
"canal": "whatsapp", "origem_id": 3, "campanha": "Site da loja", "id_externo": "contato-8841" }'
nomeé obrigatório, e precisa ter pelo menostelefoneouemail. O resto é opcional.veiculo_idé oiddo veículo nas rotas de estoque. Veículo que não existe na loja dá erro422(veiculo_inexistente).canal:formulario(padrão),whatsapp,telefone,emailouchat.campanhaé um texto livre que vai na descrição do lead, como "Black Friday".origem_idé a origem do cliente (Instagram, Indicação, Site...). Pegue a lista emGET /v1/leads/origens, que traz as mesmas origens cadastradas no painel em Configurações > Origens do cliente. Origem que não existe na loja dá erro422(origem_inexistente).id_externoé o número do contato no sistema do parceiro: reenviar o mesmo não cria lead repetido.- O lead entra como Não atribuído, com a origem escolhida (sem
origem_id, a origem Integração (API)), a mensagem, o link do WhatsApp e o veículo. Se o cliente já é atendido por um vendedor, o lead vai direto para ele. Se o mesmo cliente já tem lead aberto para o mesmo veículo, o contato entra no histórico desse lead em vez de duplicar. - A resposta traz o número do lead e o
resultado:novo(status201),interacaoourepetido(status200).
Filtros, ordem e páginas da lista de veículos
pagina(começa em 1) epor_pagina(padrão 50, máximo 100).marca,ano_min,ano_maxepreco_max(em reais, com ponto decimal). O ano é o ano do modelo; compreco_max, os veículos com preço escondido no site ficam de fora.- Parâmetro com nome errado é ignorado, sem erro: se um filtro parecer não funcionar, confira a grafia. Valor fora do formato dá
400. atualizado_desde: só os veículos alterados a partir da data, no formato ISO 8601 (ex.:2026-10-01T00:00:00Z).ordenar:-id(padrão, mais novos primeiro),id,preco,-preco,atualizado_emou-atualizado_em. O sinal de menos na frente inverte a ordem.
Formato da resposta
A lista vem em dados, com a paginacao e os links para a próxima página. Siga links.proxima até ela vir null. Um veículo só vem em dados. Datas em ISO 8601 (UTC). Preço null quando a loja esconde o preço no site.
{
"dados": [
{ "id": 1532, "marca": "FIAT", "modelo": "Argo", "versao": "1.0 Drive",
"ano_fabricacao": 2022, "ano_modelo": 2023, "quilometragem": 31000,
"combustivel": "Flex", "cambio": "Manual", "cor": "Branco", "portas": 4,
"preco": 69900.0, "zero_km": false, "categoria": "carro",
"opcionais": ["Ar condicionado", "Direção elétrica"],
"fotos": ["https://..."], "atualizado_em": "2026-10-05T18:20:00.000Z" }
],
"paginacao": { "pagina": 1, "por_pagina": 50, "total": 87, "total_paginas": 2 },
"links": { "self": "/v1/veiculos?por_pagina=50&ordenar=-id&pagina=1",
"proxima": "/v1/veiculos?por_pagina=50&ordenar=-id&pagina=2", "anterior": null }
}
Erros
Todo erro vem no padrão RFC 9457 (application/problem+json), com um codigo fixo para o sistema testar e o request_id, que deve ser informado ao suporte.
{ "type": "https://api.itcar.com.br/docs#erros", "title": "Nao autenticado", "status": 401,
"detail": "Chave invalida.", "codigo": "nao_autenticado", "request_id": "..." }
- 400
parametro_invalidoourequisicao_invalida: filtro ou campo fora do formato (no lead: falta nome, ou telefone e e-mail). - 401
nao_autenticado,chave_revogada,chave_vencidaouchave_sem_responsavel: falta a chave, ela está errada, foi desativada pela loja, venceu, ou quem a gerou não pode mais gerar chaves na loja (tipo de usuário mudou ou saiu). - 403
sem_permissao,revenda_inativaourevenda_invalida;sem_vendedor_vinculado: chave de "Meus leads e minhas vendas" cujo criador não está ligado a um vendedor. - 404
nao_encontrado: o veículo não existe ou, na rota de estoque, não está publicado no site (vendido ou tirado do site);rota_inexistente: rota errada. - 422
veiculo_inexistenteouorigem_inexistente: oveiculo_idou oorigem_iddo lead não existe na loja. - 429
limite_excedido,cota_diaria_excedida,chamadas_simultaneasouip_bloqueado: espere os segundos do cabeçalhoRetry-After. - 503
indisponivel: instabilidade passageira. Tente de novo depois doRetry-After.
Limites de uso
- Por chave: 60 chamadas por minuto, 10.000 por dia e até 5 chamadas ao mesmo tempo.
- Cada resposta traz quanto ainda resta:
RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset(segundos),X-Cota-Diaria-LimiteeX-Cota-Diaria-Restante. Toda resposta traz também oX-Request-Id, o mesmorequest_iddos erros. - Quem errar a chave 10 vezes seguidas fica bloqueado por 15 minutos naquele IP.
- Guarde o
ETagda resposta e mande no cabeçalhoIf-None-Matchda próxima chamada: se nada mudou, a resposta é304, sem conteúdo.
Como manter o estoque sincronizado
- Uma vez por dia, faça a carga completa (todas as páginas). Ela também tira do seu sistema os veículos que foram vendidos, porque eles somem da lista.
- A cada 5 a 15 minutos, peça só
atualizado_desdecom a data da última sincronização. - Troca só de fotos não muda
atualizado_em: a carga diária pega essas mudanças.
Cuidados de segurança
- Guarde a chave no servidor do parceiro, nunca em página de site, aplicativo instalado no celular, planilha compartilhada ou grupo de mensagem.
- Uma chave para cada parceiro. Assim dá para desativar um sem atrapalhar os outros.
- Se desconfiar que a chave vazou, desative na hora e gere outra.
Resumo: o que a API faz, em poucas palavras
- Para que serve: deixa outro sistema (site, CRM, sistema de gestão) ou uma inteligência artificial ler os dados da loja, sempre atualizados, e mandar interessados direto para a Gestão de Leads.
- Duas permissões de leitura: Estoque publicado mostra só o que o site já mostra (marca, modelo, versão, ano, km, cor, câmbio, combustível, motor, portas, preço, opcionais, observações do anúncio, fotos e vídeo). Dados de gestão mostra todos os veículos com placa, chassi, Renavam, observações internas, compra, venda, troca, financiamento, custos, resultado e as contas a pagar e a receber. E toda chave pode criar leads na Gestão de Leads.
- Quase tudo é consulta: a única coisa que a API grava são leads novos na Gestão de Leads. Ela não altera e não apaga nada no painel.
- Dados de pessoas: com a permissão Dados de gestão, clientes e fornecedores vêm com o cadastro completo (nome, CPF/CNPJ, RG, nascimento, telefones, e-mail e endereço). Senhas e dados bancários nunca aparecem.
- Feito para IA: a ficha de cada veículo traz uma frase pronta com o essencial (compra, venda, custos e resultado), e o resumo da loja mostra estoque, vendas do mês e contas em aberto numa chamada só.
- Buscas possíveis: por marca, por ano, por preço máximo, do mais barato ao mais caro (ou ao contrário) e só os veículos que mudaram desde uma data.
- Quem libera: o administrador da loja (ou quem ele autorizar, só para o estoque) gera uma chave para cada sistema ou parceiro, aceitando o termo de uso e proteção de dados (LGPD), e pode desativar qualquer uma na hora.
- No ChatGPT e no Claude: conector pronto no endereço
https://api.itcar.com.br/mcp; é só colar a chave na tela da ItCar que abre ao conectar. - Para começar: gere a chave em Configurações > Integrações > API de integração e mande para o técnico do parceiro junto com o link deste artigo.
Também procurado como: API, chave de API, token, integração, integrar sistema, conectar CRM, conectar site, ChatGPT, inteligência artificial, IA, desenvolvedor, programador, estoque por API, feed de estoque, XML de estoque, JSON, gestão por API, financeiro por API, contas a pagar, contas a receber, lucro por veículo, contador, BI, LGPD, termo de uso, permissão para gerar chave, tipo de usuário, gerente gerar chave, enviar lead, receber lead, lead do site, formulário do site, landing page, robô de WhatsApp, chatbot, webhook de lead, Claude, conector, MCP, perguntar para a IA, assistente de IA, conversar com os dados, leads parados, carros parados, margem, ranking de vendedores, conversão de leads, fluxo de caixa, chave do vendedor, meus leads, minhas vendas.
Sem acento: integracao, permissoes, gestao, tecnico, inteligencia, veiculo, permissao, usuario, formulario, robo, conversao.