Como conectar outro sistema ou uma IA aos dados da loja (API de integração)

Rodrigo Carneiro

Rodrigo Carneiro

Última atualização em Oct 6, 2026

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

  1. 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.
  2. Em Gerar nova chave, escreva para quem é a chave (ex.: "Site da agência X" ou "Assistente de IA").
  3. 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.
  4. Escolha a Validade (90 dias, 6 meses ou 1 ano).
  5. 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.
  6. Digite a sua senha do painel e clique em Gerar chave.
  7. 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 ...".

  1. Gere uma chave nesta tela. Para perguntas sobre lucro, compras, vendas e contas, marque Dados de gestão.
  2. 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.
  3. 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/mcp e escolha autenticação OAuth.
  4. 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 em Authorization: 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/leads e GET /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_de e vendido_ate (aaaa-mm-dd). Ordem: ordenar com -id (padrão), id, -data_venda ou data_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 campo resumo_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, vencida ou quitada) e o cadastro completo do cliente ou fornecedor. Filtros: tipo (pagar ou receber), situacao, vencimento_de, vencimento_ate e veiculo_id. situacao=aberta traz também as vencidas.
  • GET /v1/gestao/leads: os leads da Gestão de Leads, com situação, resultado (ganho, perdido ou em_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_de e aberto_ate, contato_atrasado=true. Ordem: -id (padrão), id, proximo_contato ou -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 (de e ate; 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 menos telefone ou email. O resto é opcional.
  • veiculo_id é o id do veículo nas rotas de estoque. Veículo que não existe na loja dá erro 422 (veiculo_inexistente).
  • canal: formulario (padrão), whatsapp, telefone, email ou chat. 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 em GET /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á erro 422 (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 (status 201), interacao ou repetido (status 200).

Filtros, ordem e páginas da lista de veículos

  • pagina (começa em 1) e por_pagina (padrão 50, máximo 100).
  • marca, ano_min, ano_max e preco_max (em reais, com ponto decimal). O ano é o ano do modelo; com preco_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_em ou -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_invalido ou requisicao_invalida: filtro ou campo fora do formato (no lead: falta nome, ou telefone e e-mail).
  • 401 nao_autenticado, chave_revogada, chave_vencida ou chave_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_inativa ou revenda_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_inexistente ou origem_inexistente: o veiculo_id ou o origem_id do lead não existe na loja.
  • 429 limite_excedido, cota_diaria_excedida, chamadas_simultaneas ou ip_bloqueado: espere os segundos do cabeçalho Retry-After.
  • 503 indisponivel: instabilidade passageira. Tente de novo depois do Retry-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-Limite e X-Cota-Diaria-Restante. Toda resposta traz também o X-Request-Id, o mesmo request_id dos erros.
  • Quem errar a chave 10 vezes seguidas fica bloqueado por 15 minutos naquele IP.
  • Guarde o ETag da resposta e mande no cabeçalho If-None-Match da próxima chamada: se nada mudou, a resposta é 304, sem conteúdo.

Como manter o estoque sincronizado

  1. 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.
  2. A cada 5 a 15 minutos, peça só atualizado_desde com a data da última sincronização.
  3. 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.