Autenticação

A chave de API no cabeçalho Authorization: onde gerar, como guardar e como revogar.

Toda chamada à /v1 leva a sua chave no cabeçalho Authorization, no formato Bearer. O cabeçalho X-API-Key também é aceito. Não há OAuth nem token de sessão: a chave é a credencial.

HTTPcabeçalho recomendado

Authorization: Bearer zc_live_sua_chave_aqui

HTTPalternativa aceita

X-API-Key: zc_live_sua_chave_aqui

cURLchamada autenticada

curl "https://api.zapcarconsulta.com.br/v1/saldo" \
  -H "Authorization: Bearer $ZAPCAR_API_KEY"

Tipos de chave

Prefixo	Ambiente	O que acontece
`zc_live_`	Produção	Consulta as bases reais e debita o saldo da carteira.
`zc_test_`	Teste (sandbox)	Mesma URL e mesmos endpoints, sem débito, sem base real e sem dado pessoal verdadeiro. Toda resposta traz `ambiente: "test"`. Ver Sandbox.

A chave atua como o titular da conta: acesso ao catálogo, ao saldo e às consultas dela. Cada conta pode ter uma chave ativa por ambiente, então a chave de teste e a de produção convivem.

Onde gerar a chave

No Portal do Cliente, em Conta › Integrações: Gerar nova chave (produção) ou Chave de teste. O titular da conta ou um administrador gera na hora, sem pedido de liberação; operadores não gerenciam chaves.

A chave aparece uma única vez

Guardamos apenas o hash SHA-256 da chave: nem a equipe da ZapCar consegue lê-la depois. Se você perdeu a chave, gere outra.

Respostas de autenticação

200
Chave válida
A chamada segue normalmente.
401
Cabeçalho ausente: MISSING_API_KEY
Faltou Authorization: Bearer … (ou X-API-Key).
401
Chave inválida ou revogada: INVALID_API_KEY
A revogação tem efeito imediato.
401
Conta não encontrada: CUSTOMER_NOT_FOUND
A chave existe, mas a conta associada a ela não. Fale com o suporte.

Guarda da chave

Nunca exponha a chave no navegador ou em app mobile

Código de front-end é público por definição: minificar não esconde nada, e um app publicado pode ser descompilado. Quem tem a chave de produção consulta no seu nome e gasta o seu saldo. Guarde-a numa variável de ambiente do servidor, chame a API pelo seu backend e devolva ao navegador só o que ele precisa mostrar.

Regra	Por quê
Chave no servidor, em variável de ambiente ou cofre de segredos.	Fora do repositório, do bundle do front-end e de planilhas.
Nunca em URL, query string ou log.	URL vai para histórico, proxy e log de acesso. A chave vai no cabeçalho, e em mais nada.
Uma chave por sistema integrado, quando possível.	Revogar uma não derruba as outras integrações.
Rotacione ao trocar de fornecedor, ao desligar alguém com acesso ou na dúvida.	Revogar tem efeito imediato. Veja abaixo como trocar com o mínimo de interrupção.

Rotação sem interrupção

O portal permite uma chave ativa por ambiente: para gerar a nova, é preciso revogar a atual primeiro. Entre a revogação e a publicação da chave nova no seu servidor, as chamadas recebem 401 INVALID_API_KEY. Para encurtar essa janela:

escolha um momento de pouco tráfego e deixe o seu sistema pronto para receber a chave nova (variável de ambiente ou cofre de segredos, sem novo deploy de código);
revogue a chave atual e gere a nova em seguida, em Conta › Integrações;
publique a chave nova e confirme com GET /v1/servicos;
reprocesse o que falhou com 401 nesse intervalo: nada foi criado nem cobrado nessas chamadas.

Use a resposta 401 INVALID_API_KEY como alarme no seu monitoramento: fora de uma rotação planejada, ela indica chave revogada ou trocada.

Suspeita de vazamento? Revogue no portal (efeito imediato) 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.