Integração OLX revenda: anúncios, leads e análise veicular

A integração OLX revenda precisa separar publicação de estoque, atendimento de interessados e análise documental interna. Quando a loja mistura essas tarefas, o orçamento pode incluir recursos cujo acesso ainda não foi confirmado.

Antes de contratar o desenvolvimento, confirme quais operações a OLX oferece para a sua conta. Acesso a anúncios não comprova acesso a leads ou consulta avulsa por placa.. [1] [2] [3]

Separe anúncios, leads e consulta veicular antes de integrar

Um ERP pode coordenar as três tarefas, mas cada componente precisa de um contrato técnico próprio. Na entrada de um carro, a análise documental atende à decisão de compra. A publicação usa os campos comerciais aprovados pela loja; o atendimento depende do acesso aos contatos recebidos.

Qual integração atende a cada tarefa da revenda?

Distribuir anúncios e consultar um veículo resolvem problemas diferentes. A análise interna deve funcionar mesmo quando a loja decide não publicar o carro. Para definir esse componente, veja quando usar uma API veicular. [1]

Confira plano, site e acesso antes de estimar a integração OLX revenda

Plano contratado, origem do estoque e acesso técnico precisam entrar na conferência inicial. Não use nomes de planos encontrados em materiais anteriores como confirmação de elegibilidade atual.. [1]

Planos e requisito de site documentados

Antes do orçamento, peça confirmação destas três dependências:

• O plano empresarial da loja permite o modelo de integração pretendido.
• A origem dos anúncios atende ao requisito de site, caso ele permaneça aplicável.
• O CRM ou integrador consegue cumprir os parâmetros do manual vigente. [1]

Um ERP com estoque cadastrado não comprova, por si só, elegibilidade. Se o sistema alimenta um site, apresente esse caminho na descrição da arquitetura. Para contextualizar a operação comercial, consulte o conteúdo sobre OLX para revendas. [1]

Perguntas que precisam de resposta da OLX

Envie a arquitetura pretendida e peça respostas sobre:

• Credenciais, requisitos de aprovação e versão vigente do manual.
• Limites de uso, suporte técnico e condições para o modelo da loja.
• Disponibilidade de captação de leads e operações suportadas.
• Identificadores dos leads, mecanismo de entrega e regras de acesso.
• Condições comerciais do plano e eventual acesso à integração.

Separe custos de plano, integrador, desenvolvimento, manutenção e consultas veiculares. Não atribua preço ou taxa à integração OLX sem proposta vigente. No orçamento, identifique o que depende de confirmação comercial e o que depende de documentação técnica.

Relacione o anúncio ao estoque e acompanhe o Histórico Veicular

O hatch recebido na troca precisa continuar identificável durante publicação, alterações e venda. Use um cadastro interno estável, mesmo que o integrador adote outros identificadores.. [4]

Inserção, edição e retirada com correspondência interna

Organize a sincronização em três etapas:

1. 1.Crie o cadastro interno e registre sua correspondência com os identificadores exigidos pelo contrato de publicação.
2. 2.Nas edições, preserve essa correspondência e acompanhe o resultado da operação.
3. 3.Na venda, solicite a retirada pelo fluxo confirmado e registre o retorno antes de encerrar a tarefa. [4]

Mantenha separados o status do estoque e o status da publicação. Um carro vendido pode ter uma retirada ainda pendente. Nesse caso, o ERP deve mostrar a pendência, em vez de considerar o anúncio removido após o envio da solicitação.

clientAdId, processamento e exibição pública

Antes de usar `clientAdId`, confirme sua função e as operações disponíveis para o Histórico Veicular. Depois, registre a correspondência com o cadastro interno. Não o confunda com o identificador de uma consulta independente.. [2] [3]

Não implemente regras de processamento com estados copiados de uma versão não validada.. [2]

Também confira o conteúdo efetivamente oferecido no anúncio.. [3]

A publicação precisa de regras próprias para dados pessoais e identificadores do veículo.. [3]

Organize entrada, publicação e venda em fluxos separados

Nesse cenário, a avaliação da compra não deve depender da publicação. O cadastro comercial pode permanecer em preparação enquanto a loja confere uma pendência documental. Já o atendimento só deve usar leads da OLX depois da confirmação do acesso e do mecanismo de entrega.

Checklist de entrada antes da publicação

1. 1.Cadastre o hatch com um identificador interno estável.
2. 2.Confira os documentos e a correspondência entre o veículo apresentado e seu cadastro.
3. 3.Solicite a consulta adequada à avaliação pretendida.
4. 4.Registre pendências e avalie o resultado antes de decidir a compra.
5. 5.Prepare os campos comerciais permitidos e encaminhe o anúncio pelo fluxo validado.

Relacione o identificador interno do veículo, o `id` da consulta e o identificador exigido pela publicação. Essa correspondência permite localizar a análise sem usar nome ou CPF/CNPJ do proprietário como identificador público.

Para integrar dados veiculares ao fluxo da empresa, mantenha os componentes independentes. A consulta veicular no CRM pode apoiar a avaliação interna. Ela não comprova acesso aos leads da OLX.

Dados internos não devem virar conteúdo público

Defina uma lista de campos permitidos para publicação e confira sua compatibilidade com o manual vigente. Selecione informações comerciais do cadastro, sem copiar automaticamente o JSON da consulta interna.

Restrinja dados pessoais e documentos aos usuários que precisam deles na análise. Um interessado responder ao anúncio não justifica encaminhar o relatório completo ao atendimento comercial. Prepare a resposta comercial com os dados apropriados à negociação.

Na venda, atualize o estoque, solicite a retirada do anúncio e acompanhe o retorno. Preserve a análise interna conforme a política de acesso e retenção da empresa. Inclua o custo da consulta e as pendências confirmadas na avaliação da margem, sem substituir a inspeção e a conferência documental.

Use a API da ZapCar para a análise interna do veículo

A consulta independente pode apoiar a conferência de restrições e pendências antes da publicação. Esse acesso não habilita anúncios ou leads na OLX. Também não representa parceria ou integração nativa entre os fornecedores.

Catálogo, autenticação e saldo

Use a base `https://api.zapcarconsulta.com.br` com o cabeçalho `Authorization: Bearer zc_live_SUA_CHAVE`. Gere a chave no Portal do Cliente. Ela pode ser revogada e age como a conta, sem escopos.

Mantenha a credencial no backend, fora do navegador, do anúncio e de registros públicos. Para integrar consulta veicular ao ERP, comece por estas operações:

• `GET /v1/servicos`: consulta o catálogo e os preços vigentes por serviço.
• `GET /v1/saldo`: verifica o saldo disponível na carteira.
• Recarga por PIX no portal: adiciona saldo à carteira pré-paga; não existe endpoint de recarga pela API.

Criação da consulta e recuperação do resultado

Este exemplo solicita a Consulta Completa com uma placa fictícia:

```http POST /v1/consultas HTTP/1.1 Host: api.zapcarconsulta.com.br Authorization: Bearer zc_live_SUA_CHAVE Content-Type: application/json

{"servico":"consulta-completa","placa":"ABC1D23"} ```

Conforme o serviço, a identificação pode usar placa, chassi, motor ou documento. Alguns serviços também exigem UF, RENAVAM ou CPF. Confira os requisitos antes de montar um formulário único para o catálogo.

O POST responde com HTTP `201`, um `id` e status `processando`. Grave esse identificador e acompanhe por `GET /v1/consultas/:id`. Quando a consulta termina com sucesso, a resposta disponibiliza `dados` e `pdf_url`.

A Consulta Completa apoia a conferência de restrições, gravame, débitos, leilão e indicador de sinistro, quando disponível nas fontes consultadas. O proprietário atual também depende dessa disponibilidade. A consulta não entrega a cadeia de proprietários anteriores.

Trate processamento, falhas e notificações antes da produção

O processamento assíncrono precisa de acompanhamento fora da requisição principal do ERP. Após criar a consulta, mostre o estado de processamento e permita que o usuário continue o cadastro. A decisão de compra deve permanecer separada desse retorno técnico.

Polling, saldo e estorno

Os estados públicos são `processando`, `concluido` e `erro`. Enquanto houver processamento, mantenha a análise pendente. Depois da conclusão, encaminhe o resultado para avaliação, sem transformar ausência de apontamentos em aprovação automática.

Faça polling a cada 3–5 segundos, com teto operacional de aproximadamente 5 minutos. Esse teto encerra o acompanhamento ativo da aplicação; não garante conclusão. A maioria das consultas é processada automaticamente e fica pronta em poucos minutos. O tempo pode variar conforme a fonte consultada e a UF.

Implemente estes controles:

• O POST debita o saldo; HTTP `402 SALDO_INSUFICIENTE` não gera cobrança.
• Uma consulta finalizada em `erro` recebe estorno automático.
• Pedido idêntico em andamento retorna a consulta existente com `reaproveitada: true`, sem nova cobrança.
• O limite é de 120 requisições por minuto por chave; ao excedê-lo, trate `429 RATE_LIMITED`.
• Erros temporários `503` sinalizados como `retryable` exigem repetição controlada.

O reaproveitamento de pedido em andamento não garante idempotência para qualquer repetição. Consulte os códigos em `GET /public/api-erros`. Registre `codigo` e `request_id` para investigar falhas sem expor credenciais nos logs.

Webhooks e testes com dados fictícios

No webhook de consulta, trate `query.completed` e `query.failed`. Valide `X-ZapCar-Signature`, no formato `t=<timestamp>,v1=<assinatura>`. Calcule HMAC-SHA256 de `<timestamp>.<corpo>` com o secret do endpoint.

Use `X-ZapCar-Delivery` como identificador de idempotência da entrega. Há reentregas com backoff exponencial, até 6 tentativas, enquanto o endpoint não responder com HTTP 2xx. Não aplique a mesma atualização ao estoque novamente ao receber uma entrega repetida.

Uma chave de teste com prefixo `zc_test_`, gerada no portal, permite testar sem debitar saldo ou chamar fornecedor. As respostas incluem `ambiente: "test"` e dados fictícios. Cubra estes cenários:

• `TST0001`: veículo sem apontamentos no cenário de teste.
• `TST0002`: gravame.
• `TST0003`: RENAJUD.
• `TST0004`: débitos.
• `TST0503`: falha temporária.
• `TST9999`: consulta que nunca conclui.

Evite erros que misturam publicação e análise documental

Antes de liberar a publicação, confira se o registro aponta para o veículo correto. Verifique também se algum campo pessoal entrou no conteúdo comercial. A existência de um Histórico Veicular associado ao anúncio não dispensa essa conferência no fluxo interno.

Conclusão

A entrega deve acompanhar o contrato técnico confirmado, não o nome comercial do recurso.. [1] [2] [3]

Transforme cada componente em um critério de aceite:

• Publicação: conferir elegibilidade, correspondência dos anúncios e operações de manutenção.
• Atendimento: confirmar acesso e contrato de leads antes da implementação.
• Histórico no anúncio: validar associação, processamento e remoção.
• Análise interna: definir consulta, permissões, custos e avaliação do resultado.

Para o hatch recebido na troca, a compra pode seguir em análise enquanto o anúncio permanece em preparação. O ERP precisa representar essa diferença sem misturar os estados. Orce cada componente separadamente e deixe fora da entrega os recursos ainda sem confirmação técnica.

Próximo passo

Envie uma ficha de escopo à OLX antes de fechar o desenvolvimento. Descreva como o estoque sai do ERP, se existe site e como o CRM receberia os interessados. Peça confirmação de plano, acesso, operações de leads, limites e condições comerciais. [1]

Na mesma ficha, separe as dúvidas em três blocos:

• Publicação: origem dos anúncios, identificadores e operações pretendidas.
• Atendimento: dados esperados, mecanismo de entrega e regras de acesso.
• Análise interna: consulta independente, sem pressupor vínculo com anúncios ou leads.

Use essa ficha como base para o aceite técnico do orçamento. A API da ZapCar para ERP e CRM corresponde ao componente de consulta interna; não atribua a ela as funções de publicação ou atendimento da OLX.