Guia
Primeira Integração em 10 Minutos
Trilha rápida para sair do zero até criar o primeiro anúncio em rascunho com autenticação e oficial.
Atualizado em 2026-04-10
1. Solicite onboarding de integração
- Abra a solicitação no formulário oficial com dados técnicos e de negócio.
- Se preferir fluxo API-first, abra com POST /web/v1/client/integration-requests.
- Informe cenários de integração (browser, backend-to-backend, jobs, etc.).
- Declare antecipadamente se precisa de web.client.integration.
- A criação do service client é da QueroTruck.
2. Receba provisionamento e credenciais
client_id provisionado internamente.
Credencial inicial entregue por canal seguro.
Confirmação dos scopes liberados para o ambiente.
Validação de allowedOrigins quando houver integração browser.
3. Faça login via OIDC (PKCE)
- Leia .
- Faça a autorização ().
- Troque o code no e obtenha access_token.
- Guarde o e renove o access_token sem reabrir tela de login.
4. Consulte catálogo antes de montar payload
Listar tipos de anúncios ativos.
Listar categorias por kind.
Validar cadeia marca > modelo > versão > ano.
Consultar opcionais (vehicle-options/add-info).
5. Crie anúncio em rascunho
Envie isDraft=true no primeiro envio. Isso permite construir o anúncio por etapas sem falhar por falta de mídia ou campos de publicação.
- POST
- Antes do create, gere / no Profiles.
- Use idempotente desde o primeiro create.
- Preencha o bloco técnico correto por tipo de anúncio (vehicle, implement, agriculturalMachine, civilMachine, utilityDetails).
6. Envie mídia e publique
- /vídeo.
- Reordene e marque principal.
- Atualize anúncio com isDraft=false quando regras de publicação estiverem atendidas.
7. Ative observabilidade mínima
Enviar X-Correlation-Id em toda chamada.
Tratar 401/403/422 com mensagens amigáveis para o operador.
Registrar request/response por correlation id para suporte.
Rota curta recomendada
Com esta sequência, o time parceiro normalmente fecha a primeira publicação operacional sem dependências ocultas.