API para Revendas

Como começar

A API é de somente leitura: ela devolve os dados da sua revenda, mas nenhuma requisição altera ou apaga informação no Click Garage.

Para usar, você precisa de um token de acesso. Solicite o seu ao nosso suporte informando o que pretende integrar — nós geramos o token liberando apenas as informações necessárias e enviamos para você.

Guarde o token em segurança. Ele dá acesso aos dados da sua revenda e não pode ser consultado depois de gerado. Se for perdido ou exposto, avise o suporte para revogá-lo e gerar outro.

Endereço e autenticação

Todas as chamadas partem de https://api.clickgarage.com.br/v1 e devem enviar o token no cabeçalho Authorization:

curl https://api.clickgarage.com.br/v1/veiculos \ -H "Authorization: Bearer SEU_TOKEN_AQUI"

Para conferir se o token está funcionando, chame a raiz da API. Ela devolve o nome da sua revenda e a lista de informações que aquele token pode ler:

GET https://api.clickgarage.com.br/v1 { "versao": "v1", "revenda": { "nome": "Sua Revenda", "slug": "sua-revenda" }, "escopos": ["veiculos.ficha", "financeiro.extrato"] }

Permissões do token

Cada token libera apenas as informações combinadas. Se o token não tiver a permissão de um endereço, a resposta é 403; se não tiver a permissão de um grupo de campos, esses campos simplesmente não aparecem na resposta.

Módulo	Permissão	O que libera
Veículos	`veiculos.ficha`	Marca, modelo, versão, ano, cor, placa, quilometragem, portas, câmbio, combustível, fotos, acessórios, observações, situação e loja.
Veículos	`veiculos.valores`	Valor de venda, valor pago na aquisição, despesas e lucro do veículo.
Financeiro	`financeiro.contas-a-pagar`	Despesas com parcelas, vencimentos, categoria e situação.
Financeiro	`financeiro.contas-a-receber`	Receitas com parcelas, vencimentos, categoria e situação.
Financeiro	`financeiro.extrato`	Lançamentos realizados em um período, com conta, categoria e valor.
Financeiro	`financeiro.contas`	Contas cadastradas e o saldo atual de cada uma.

Paginação

As listagens vêm paginadas. Use page para navegar e por_pagina para escolher quantos itens vêm por vez (padrão 50, máximo 200).

GET /v1/veiculos?page=2&por_pagina=100 { "current_page": 2, "data": [ ... ], "per_page": 100, "total": 343, "last_page": 4, "next_page_url": "https://api.clickgarage.com.br/v1/veiculos?page=3" }

Filtros e ordenação

Os filtros são combináveis: mande quantos quiser na mesma chamada e todos são aplicados juntos. Parâmetro em branco é ignorado, e parâmetro que a API não conhece também.

Filtros de texto (busca, marca, modelo) buscam por parte da palavra e não diferenciam maiúsculas de minúsculas. Datas usam sempre o formato AAAA-MM-DD. Valores usam ponto como separador decimal.

Toda listagem aceita ordenar e ordem (asc ou desc, sendo desc o padrão). Os campos aceitos em ordenar mudam por endereço e estão descritos em cada um.

GET /v1/veiculos?situacao=estoque&marca=fiat&ano_min=2020&valor_max=90000&ordenar=valor&ordem=asc

Valor inválido devolve erro, não lista vazia. Se você mandar um filtro com valor que a API não aceita — uma data fora do formato, ou situacao=disponivel — a resposta é 422 dizendo qual parâmetro está errado e quais valores são aceitos. Assim você não corre o risco de achar que filtrou e receber dados errados.

Veículos

Lista os veículos da revenda, do mais recente para o mais antigo.

Parâmetro	Descrição
`situacao`	`estoque`, `vendido` ou `todos`. Sem o parâmetro, vêm todos.
`placa`	Filtra por uma placa específica.
`busca`	Procura o texto no título do veículo ou na placa.
`loja`	ID da loja. O ID vem no campo `loja_id` da resposta.
`status`	Nome do status como aparece no Click Garage, por exemplo `Showroom` ou `Reservado`.
`marca`	Nome da marca, por parte do nome. Ex.: `fiat`.
`modelo`	Nome do modelo, por parte do nome. Ex.: `onix`.
`combustivel`	Ex.: `flex`, `diesel`.
`cor`	Ex.: `prata`.
`ano_min` / `ano_max`	Faixa de ano do modelo.
`valor_min` / `valor_max`	Faixa do valor anunciado.
`km_max`	Quilometragem máxima.
`cadastrado_desde` / `cadastrado_ate`	Faixa da data de cadastro do veículo.
`vendido_desde` / `vendido_ate`	Faixa da data da venda. Útil para relatório de vendas por período.
`atualizado_desde`	Traz só o que mudou a partir da data — use para sincronizar sem baixar tudo de novo.
`ordenar`	`cadastro` (padrão), `atualizacao`, `valor`, `km` ou `venda`.
`ordem`	`asc` ou `desc` (padrão).

{ "id": 267787, "situacao": "estoque", "status": "Showroom", "tipo": "Carros", "marca": "VW - VolksWagen", "modelo": "Polo", "versao": "Polo Track First Edition 1.0 Flex 12V 5p", "titulo": "VW - VolksWagen Polo Track 1.0 Flex 2023", "codigo_fipe": "005504-1", "ano_modelo": 2023, "ano_fabricacao": 2023, "combustivel": "Flex", "cambio": "MANUAL", "motor": "1.0", "cor": "VERMELHA", "portas": "4", "placa": "ABC1D23", "km": 25131, "loja": "MATRIZ", "loja_id": 812, "observacoes": "Veículo revisado, único dono.", "acessorios": ["Airbag", "Ar condicionado", "Freio ABS"], "imagem_principal": "https://storage.clickgarage.com.br/veiculos/...jpg", "galeria": ["https://storage.clickgarage.com.br/veiculos/...jpg"], "data_cadastro": "2026-08-19 15:02:08", "data_atualizacao": "2026-08-20 09:03:33", "valor_anunciado": 81900, "valor_venda": null, "valor_pago": 70000, "proveniencia": "PROPRIO", "data_venda": null, "despesas": 1200, "custo_total": 71200, "margem": 10700 }

Os seis últimos campos (de valor_anunciado a margem) só aparecem se o token tiver a permissão veiculos.valores.

Traz um veículo específico, com os mesmos campos da listagem. Devolve 404 se o veículo não existir ou não pertencer à sua revenda.

Financeiro

Em contas-a-pagar, contas-a-receber e extrato você filtra o período com inicio e fim. O endereço contas não usa período: ele mostra o saldo acumulado de cada conta.

Período padrão de 12 meses. Em contas-a-pagar e contas-a-receber, se você não mandar inicio, ele é calculado como 12 meses antes do fim — ou 12 meses atrás, quando também não há fim. Isso evita varrer todo o histórico da revenda sem querer. Para buscar mais fundo, é só informar inicio.

O topo do período continua aberto quando você não manda fim, de propósito: assim as parcelas a vencer continuam aparecendo, que costuma ser o que se quer ver numa conta a pagar.

Parcelas de despesas. Transferências entre contas da própria revenda não entram aqui.

Parâmetro	Descrição
`inicio` / `fim`	Período. Sem `inicio`, valem os últimos 12 meses (veja o aviso acima). Sem `fim`, as parcelas a vencer continuam entrando.
`tipo_data`	Qual data o período considera: `vencimento` (padrão) ou `pagamento`. Use `pagamento` para conciliar o que saiu do caixa no período.
`situacao`	`pago` ou `pendente`.
`categoria`	ID da categoria, do campo `categoria_id` da resposta.
`conta`	ID da conta, do campo `conta_id`. A lista completa está em `/financeiro/contas`.
`veiculo_id`	Só as despesas amarradas a um veículo específico.
`forma_pagamento`	Ex.: `PIX`, `BOLETO`.
`busca`	Procura o texto na descrição ou no documento.
`ordenar`	`vencimento` (padrão), `pagamento`, `valor` ou `descricao`.
`ordem`	`asc` ou `desc` (padrão).

{ "id": 308889, "conta_a_pagar_id": 202438, "descricao": "Aluguel da loja", "documento": "NF 1234", "parcela": 3, "total_parcelas": 12, "categoria_id": 45315, "categoria": "Despesas Administrativas", "conta_id": 317, "conta": "Banco do Brasil", "veiculo_id": null, "valor": 1666.67, "valor_pago": 1666.67, "juros": 0, "descontos": 0, "vencimento": "2026-08-14", "data_pagamento": "2026-08-14", "situacao": "PAGO", "forma_pagamento": "PIX" }

Mesma estrutura e os mesmos filtros das contas a pagar, com valor_recebido e data_recebimento no lugar dos campos de pagamento.

Aqui tipo_data aceita vencimento (padrão) ou recebimento, e ordenar aceita vencimento (padrão), recebimento, valor ou descricao.

Lançamentos efetivamente pagos e recebidos no período, na ordem da data. Sem inicio e fim, traz o mês atual.

Parâmetro	Descrição
`inicio` / `fim`	Período pela data em que o dinheiro entrou ou saiu. Padrão: mês atual.
`tipo`	`despesa` ou `receita`. Sem o parâmetro, vêm os dois.
`conta`	ID da conta.
`categoria`	ID da categoria.
`grupo_financeiro`	Parte do nome do grupo, por exemplo `CUSTOS` ou `DESPESAS`.
`veiculo_id`	Só os lançamentos amarrados a um veículo específico.
`transferencias`	`nao` tira as movimentações entre contas da própria revenda — use quando quiser só o que é receita e despesa de verdade.
`busca`	Procura o texto na descrição.
`ordenar`	`data` (padrão), `vencimento`, `valor` ou `descricao`.
`ordem`	`asc` ou `desc` (padrão).

{ "id": "d346121", "data": "2026-08-17", "vencimento": "2026-08-25", "descricao": "Compra de peças", "tipo": "despesa", "transferencia": false, "categoria_id": 45318, "categoria": "Manutenção de Veículos", "grupo_financeiro": "CUSTOS", "conta_id": 317, "conta": "Banco do Brasil", "valor": 100, "veiculo_id": null }

O campo tipo vale despesa ou receita, e transferencia indica movimentações entre contas da própria revenda.

Contas bancárias e caixas da revenda com o saldo atual. Não é paginado. Use ativa=sim ou ativa=nao para filtrar. O id daqui é o que você usa no filtro conta dos outros endereços.

[ { "id": 1415, "nome": "Banco do Brasil", "ativa": true, "saldo_inicial": 60000, "total_recebido": 1601931.67, "total_pago": 1250658.39, "saldo": 411273.28 } ]

Limite de uso

Cada token pode fazer até 120 requisições por minuto. Toda resposta traz o quanto ainda resta:

X-RateLimit-Limit: 120 X-RateLimit-Remaining: 117

Ao passar do limite, a resposta é 429 e o cabeçalho Retry-After informa em quantos segundos você pode tentar de novo.

Erros

Os erros vêm em JSON, com um código fixo em erro e uma explicação em mensagem:

{ "erro": "escopo_nao_autorizado", "mensagem": "Este token não tem permissão para acessar estes dados.", "escopo_necessario": "financeiro.extrato" }

Código HTTP	Quando acontece
`401`	Token ausente, inválido ou revogado.
`403`	O token existe, mas não tem permissão para aquela informação.
`404`	O registro não existe, não pertence à sua revenda, ou o endereço chamado não existe.
`405`	Método não permitido — a API aceita somente `GET`.
`422`	Algum filtro veio com valor inválido. A resposta traz `parametro` com o nome do filtro e `mensagem` com os valores aceitos.
`429`	Passou do limite de requisições por minuto.

Precisa de ajuda?

Fale com o nosso suporte pelo WhatsApp (55) 98403 8873 ou pelo e-mail [email protected].