Segurança e LGPD

Guarda da chave, isolamento entre contas e as obrigações de quem recebe dado pessoal.

A chave de API

Regra	Por quê
Guarde a chave no servidor, em variável de ambiente ou cofre de segredos.	Ela dá acesso à conta e ao saldo. Quem tem a chave consulta no seu nome e gasta o seu dinheiro.
Nunca no navegador, em app mobile, em repositório ou em planilha.	Código de front-end é público por definição: minificar não esconde nada. Um app publicado pode ser descompilado.
Nunca chame a API direto do front-end do seu sistema.	Faça a chamada pelo seu backend e devolva ao navegador só o que ele precisa mostrar.
Não coloque a chave em URL, query string ou log.	URL vai para histórico, proxy e log de acesso. A chave vai no cabeçalho Authorization, e mais nada.
Revogue na dúvida.	A revogação tem efeito imediato. Ver rotação.

A chave aparece uma única vez, na criação: guardamos apenas um hash dela. Se você a perdeu, gere outra.

Os dados que você recebe

Parte dos serviços devolve dado pessoal: nome e documento do proprietário, comprador e vendedor, endereço, telefone, score, pendências financeiras, processos. Perante a LGPD, no momento em que esse dado entra no seu sistema você é controlador dele: a responsabilidade pelo uso é sua.

Obrigação	Na prática
Finalidade legítima e específica	Consulte para o negócio que justifica a consulta (avaliar um veículo, instruir uma venda, analisar crédito, atender o próprio titular). Curiosidade, vigilância e revenda de cadastro não são finalidade.
Minimização	Guarde só o que você usa. Se o seu fluxo precisa da situação do veículo, não persista o CPF do proprietário junto.
Proteção dos registros	Dado pessoal em repouso deve ficar em base com acesso controlado. Não jogue a resposta inteira num log de aplicação: log costuma ser o lugar menos protegido do sistema.
Retenção	Defina prazo e apague ao fim dele. Resultado de consulta não precisa viver para sempre.
Rastreabilidade	Registre quem, no seu sistema, pediu cada consulta. Sem isso você não responde a um pedido do titular nem a uma auditoria.

Finalidade declarada

Os serviços de dado pessoal recebem finalidade (NEGOCIACAO_VEICULO, ANALISE_CREDITO, VERIFICACAO_CADASTRAL ou OUTRA) e declaracao_finalidade: true, que ficam registradas com a consulta (quem consultou, quando e para quê).

Serviço	Finalidade na API
`comunicacao-venda` e as consultas de pessoa (`cadastro-`, `credito-`, `cnh-nacional`, `debitos-trabalhistas`, `divida-ativa`)	Obrigatória. Sem ela, `400 FINALIDADE_OBRIGATORIA` antes de cobrar.
`score-credito` e `situacao-cpf`	Registrada quando enviada; a ausência não recusa o pedido. Envie sempre: é a base legal do seu uso.

Score, crédito e cadastro não servem para montar base própria nem para decidir sobre uma pessoa sem dar a ela como contestar.

O que fazemos do nosso lado

Item	Como é
Transporte	Somente HTTPS. Webhook só é aceito em URL HTTPS.
Chave em repouso	Guardamos o hash SHA-256 da chave, nunca a chave.
Isolamento entre contas	Toda consulta é filtrada pela conta dona da chave. Um id de outro cliente responde 404, nunca o dado.
Isolamento entre ambientes	A chave de teste não enxerga consultas reais, e vice-versa.
Webhook	Assinatura HMAC-SHA256 com secret por endpoint e timestamp para você recusar entrega antiga. Destinos de rede interna são recusados no cadastro e antes de cada entrega.
Conteúdo do webhook	Não leva o resultado da consulta: só o id do evento, o tipo, a data e, em data, o id da consulta, o código interno do serviço e o status. Dado sensível sai apenas por chamada autenticada.
Mensagens de erro	Não expõem fornecedor, URL interna, token nem rastreamento de pilha.
Fornecedor	O nome das bases consultadas não aparece no contrato público (`veiculo._fonte` é sempre `"zapcar"`).

Suspeita de vazamento da chave? Revogue no portal e confira o consumo em Conta › Integrações, aba Consumo: cada consulta cobrada pela API aparece com data, serviço, chave usada e identificador consultado. A política de privacidade da ZapCar está em /privacidade e a página de segurança em /seguranca-lgpd.