Pular para o conteúdo principal

Como Começar

Este guia explica o passo a passo para começar a usar nossa API e entender como funciona a hierarquia de dados do catálogo.

Fluxo Completo de Integração​

O fluxo completo seria:

  1. ✅ Obter Client ID e Client Secret
  2. ✅ Autenticar e obter Access Token
  3. ✅ Consultar endpoints de catálogo e fazer de-para
  4. ✅ Mapear dados do seu sistema com IDs da API
  5. ✅ Criar anúncios usando os IDs mapeados
  6. ✅ Habilitar na loja os portais usados na integração (no Loja Conectada; opcionalmente espelhar no seu banco)
  7. ✅ Garantir credenciais da loja por portal registradas no Loja Conectada — ver Como Autenticar em um Portal
  8. ✅ Gerenciar anúncios (atualizar, remover, etc.)

Passo 1: Solicitar Credenciais de Acesso​

Antes de começar a usar a API, você precisa obter suas credenciais de acesso:

  1. Solicite o Client ID e Client Secret: Entre em contato com nossa equipe para obter suas credenciais de aplicativo. Essas credenciais são únicas para cada integração e são necessárias para autenticação.

  2. Guarde suas credenciais com segurança: O Client ID e Client Secret são usados em todas as requisições de autenticação e não devem ser expostos publicamente.

informação

As credenciais são enviadas nos headers das requisições de autenticação:

  • X-Client-ID: Seu Client ID
  • X-Client-Secret: Seu Client Secret

Passo 2: Ter um Usuário e Loja Ativos​

Para usar a API, você precisa ter:

  1. Usuário ativo: Uma conta de usuário válida no sistema com email e senha
  2. Loja (Dealer) ativa: Uma loja cadastrada e ativa no sistema, associada ao seu usuário

O ID da loja (dealer_id) será necessário para criar e gerenciar anúncios. Você pode consultar as lojas disponíveis através do endpoint /dealer.

dica

Ao autenticar, a resposta incluirá informações sobre a loja associada ao usuário, incluindo o dealer_id que você precisará usar nas requisições.

Antes de criar anúncios, é essencial entender a hierarquia de dados do catálogo e fazer o de-para com a base de dados do seu sistema. A hierarquia funciona da seguinte forma:

Categoria
  └── Fabricante (Brand)
      └── Modelo (Model)
          └── Versão (Version)
              └── Versão Detalhe (Version Detail)

Endpoints Disponíveis​

  1. Categorias (/catalog/category): Lista todas as categorias de veículos (Automóvel, Motocicleta, Caminhão, Implemento)

  2. Fabricantes (/catalog/brand): Lista os fabricantes/marcas. Pode ser filtrado por categoria.

  3. Modelos (/catalog/model): Lista os modelos de veículos. Pode ser filtrado por fabricante e categoria.

  4. Anos de Fabricação (/catalog/model/{id}/years): Retorna os anos disponíveis para um modelo específico.

  5. Versões Detalhadas (/catalog/versions/{model_id}): Lista as versões detalhadas de um modelo, incluindo informações como combustível, portas, transmissão, etc.

  6. Outros Endpoints de Apoio:

    • Cores (/catalog/color)
    • Opcionais (/catalog/feature)
    • Carrocerias (/catalog/body)
    • Combustíveis (/catalog/fuel)
    • Transmissões (/catalog/transmission)
    • Estados e Cidades (/catalog/state, /catalog/city/{state_id})
    • E outros...

Fazendo o De-para​

Para integrar corretamente, você precisará:

  1. Mapear categorias: Identifique qual categoria corresponde a cada tipo de veículo no seu sistema
  2. Mapear fabricantes: Faça a correspondência entre os fabricantes do seu sistema e os IDs retornados pela API
  3. Mapear modelos: Relacione os modelos do seu sistema com os IDs da API
  4. Mapear versões detalhadas: Este é o campo mais importante - o version_detail_id é obrigatório para criar anúncios
  5. Mapear outros dados: Cores, opcionais, carrocerias, etc.
aviso

O version_detail_id é essencial para criar anúncios. Certifique-se de mapear corretamente as versões detalhadas do seu sistema com os IDs da API.

Passo 4: Criar um Novo Anúncio​

Após entender o catálogo e fazer o de-para, você está pronto para criar anúncios:

  1. Consulte o guia: Leia o guia Como Criar um Novo Anúncio para entender todos os campos necessários

  2. Prepare os dados: Reúna todas as informações necessárias:

    • Dados do veículo (versão detalhada, cor, anos, etc.)
    • Informações do anúncio (preço, descrição, quilometragem, etc.)
    • Fotos em formato Base64
    • Opcionais do veículo

  3. Faça a requisição: Envie um POST para /v3/inventory/{dealer_id} com todos os dados necessários

  4. Valide a resposta: Verifique se o anúncio foi criado com sucesso e guarde o ID retornado para futuras atualizações

dica

Comece criando um anúncio de teste com dados simples para validar a integração antes de processar grandes volumes.

Passo 6: Habilitar portais para integração​

Para publicar ou integrar anúncios em sites parceiros, a loja precisa ter liberados os portais que realmente serão usados no Loja Conectada (cada portal tem regras, credenciais e planos próprios). Sem essa habilitação na plataforma, a integração com aquele destino não fica disponível para a loja.

O sistema que você está integrando pode, à parte, manter o controle dessa liberação do lado dele: por exemplo, guardar no banco de dados próprio quais portais a loja usa, telas de configuração ou regras de negócio — desde que isso reflita o que foi habilitado no Loja Conectada (via API ou fluxo operacional acordado). O catálogo da API ajuda a alinhar IDs e metadados dos portais.

Consulte a lista de portais ativos — tipos de credencial exigidos, flags de de-para etc. — no artigo Portais ativos (catálogo).

Passo 7: Credenciais da loja nos portais​

Depois que o portal está habilitado para a loja, as credenciais de acesso que o site parceiro exige (usuário, senha, token, ID etc. — conforme cada portal) precisam existir no Loja Conectada: é lá que o integrador valida e utiliza esses dados para autenticar e publicar. Não basta guardá-las apenas no seu ERP ou no banco do sistema integrador — a fonte de verdade para a integração é o cadastro na plataforma (via API ou interface, conforme o guia abaixo).

Esses valores são da conta da loja no portal externo, e são distintos do Client ID / Client Secret da API.

O passo a passo e os endpoints envolvidos estão no guia Como Autenticar em um Portal.

Próximos Passos​