Como usar a API pública e o embed do catálogo

A Torq oferece uma API REST pública (v1) e um widget embed (iframe) para que você possa exibir seu estoque em sites externos, sistemas próprios ou aplicativos. Toda comunicação é autenticada por chave de API.

A API pública e o embed são recursos exclusivos dos planos Profissional e Vitrine. No plano Profissional o limite é de 5.000 chamadas/mês; no Vitrine, 20.000 chamadas/mês.

Passo 1: Gere uma chave de API

No menu lateral, clique em Integração (seção Configurações → Integração).

Na seção Chaves de API, clique em Nova Chave.

Preencha o Nome da chave (ex.: "Meu Site") e, opcionalmente, os Domínios permitidos separados por vírgula (ex.: https://meusite.com). Restringir domínios aumenta a segurança e evita uso não autorizado da chave.

Clique em Criar Chave. O valor completo aparecerá uma única vez, então copie e guarde em local seguro. O sistema exibe apenas o prefixo (gc_live_XXXXXXXX...) nas listagens futuras.

O card Uso da API este mês na mesma página mostra quantas chamadas foram feitas no mês corrente e o limite do seu plano.

Passo 2: Revogue uma chave (quando necessário)

Na lista de chaves, clique no ícone de lixeira ao lado da chave desejada e confirme a revogação. A ação é irreversível: a chave para de funcionar imediatamente. Crie uma nova chave para substituí-la.

Passo 3: Use a API REST

Todas as requisições precisam do header x-api-key com o valor da sua chave:

x-api-key: gc_live_SUA_CHAVE_AQUI

Endpoints disponíveis

| Método | Rota | Descrição | |---|---|---| | GET | /api/v1/catalogo/veiculos | Lista veículos disponíveis (paginado) | | GET | /api/v1/catalogo/veiculos/:id | Detalhe de um veículo | | GET | /api/v1/catalogo/marcas | Marcas com veículos disponíveis | | GET | /api/v1/catalogo/marcas/:id/modelos | Modelos disponíveis de uma marca | | GET | /api/v1/catalogo/config | Configurações públicas do catálogo | | POST | /api/v1/catalogo/leads | Registra um lead (interesse em veículo) | | POST | /api/v1/catalogo/visualizacoes | Registra uma visualização de veículo |

Listar veículos com filtros

O endpoint GET /api/v1/catalogo/veiculos aceita os seguintes parâmetros de query:

page: número da página (padrão: 1)
search: busca por texto livre
ids: lista de IDs separados por vírgula para buscar veículos específicos

A resposta retorna { vehicles, total, page, totalPages }.

Criar lead via API

Envie POST /api/v1/catalogo/leads com o body JSON:

{
  "vehicleId": "uuid-do-veiculo",
  "channel": "meu-site",
  "name": "Nome do interessado",
  "phone": "11999999999",
  "message": "Tenho interesse neste veículo"
}

Apenas vehicleId é obrigatório. O lead aparecerá na seção Catálogo → Leads do painel.

Passo 4: Use o embed (widget iframe)

O embed exibe o catálogo completo dentro de qualquer página HTML, sem necessidade de desenvolvimento adicional.

Na página Integração, clique no ícone de código (<>) ao lado da chave de API que deseja usar.

O painel Código Embed exibirá o trecho HTML pronto. Clique em Copiar código.

Cole o código no HTML do seu site, substituindo o placeholder pela chave real. O trecho gerado automaticamente na tela de Integração usa o domínio do ambiente (em produção: torq.autos):

<div id="garage-catalog"></div>
<script
  src="https://torq.autos/api/v1/embed/SEU-SLUG.js"
  data-target="garage-catalog"
  data-api-key="gc_live_SUA_CHAVE_AQUI"
  async
></script>

O script cria automaticamente um <iframe> dentro do elemento #garage-catalog e ajusta a altura conforme o conteúdo. O visitante vê o catálogo com busca, grid de veículos, paginação e detalhe em modal.

Atributos do script

| Atributo | Padrão | Descrição | |---|---|---| | data-target | garage-catalog | ID do elemento HTML onde o iframe será inserido | | data-api-key | (obrigatório) | Chave de API obrigatória | | data-height | 800 | Altura inicial do iframe em pixels |

O iframe se auto-redimensiona via postMessage (gc:resize). Se precisar de uma altura fixa, use data-height no script.

Se configurar Domínios permitidos na chave de API, inclua exatamente o domínio do site onde o embed será inserido. Requisições de domínios não listados retornam erro 403.