Autenticação e limites

Chaves de API

Envie a chave no header Authorization (preferencial) ou em X-API-Key. As chaves têm 40 caracteres aleatórios após o prefixo:

dc_live_… — produção
dc_test_… — homologação (mesmos dados, cota separada por chave)

http

GET /v1/vehicles/005340-6/2015-3 HTTP/1.1
Host: datacar.digitalmart.com.br
Authorization: Bearer dc_live_3fA9…

Nunca use a chave no navegador ou em apps móveis. Faça as chamadas a partir do seu servidor. Nós armazenamos apenas um HMAC-SHA256 da chave — se você perdê-la, gere outra e revogue a antiga. A revogação vale em segundos.

Escopos

Escopo	Permite
`vehicles:read`	Consultar veículos, lote, histórico, catálogo FIPE e feed de alterações	padrão
`search:read`	Busca textual com filtros	padrão
`vin:read`	Decodificar chassi (VIN)	padrão
`usage:read`	Consultar consumo e limites	padrão
`plates:read`	Identificar veículo pela placa (provedor pago; consome 10 consultas)
`vehicles:sources`	Ver as evidências brutas de cada fonte
`vehicles:refresh`	Forçar reprocessamento de um veículo
`webhooks:manage`	Cadastrar e remover webhooks

Crie chaves com o mínimo de escopos necessário — uma para o DMS, outra para o site, por exemplo. A consulta por placa só funciona em chaves com plates:read.

Allowlist de IP

Cada chave pode ser restrita a faixas CIDR (IPv4 e IPv6), como 200.1.2.0/24. Requisições de outros IPs recebem 403 ip_not_allowed.

Rate limit

Cada chave tem um limite de requisições por minuto, com rajadas permitidas até o limite. Toda resposta informa o estado do seu balde:

http

RateLimit-Policy: 120;w=60
RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 2

Ao exceder, você recebe 429 rate_limited com Retry-After em segundos. Respeite o header e use backoff exponencial com jitter.

Cota mensal

A organização tem uma cota mensal (UTC) de consultas. Só são cobradas respostas que entregam dados: 200 em /vehicles/{fipe_code}/{year} e no histórico de preços, cada item ready do lote, cada busca e cada chassi que a NHTSA identifica. A placa consome 10 consultas (configurável) quando é encontrada. 202, 304, 404, o catálogo FIPE, a validação de código e o feed dos seus veículos não consomem cota.

http

X-Quota-Limit: 50000
X-Quota-Remaining: 48211

Consulte o consumo a qualquer momento em GET /v1/usage. Esgotada a cota, a API responde 429 quota_exceeded.

Rastreabilidade

Toda resposta traz X-Request-Id. Você pode enviar o seu próprio (8–128 caracteres [A-Za-z0-9._-]) para correlacionar logs entre sistemas. Informe-o ao suporte em caso de dúvida.