> 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](#quem-gera)).

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](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.
