Laudos Veiculares

Os laudos veiculares permitem gerar relatórios detalhados de vistoria e inspeção a partir de consultas veiculares já realizadas. Este guia cobre todo o processo de emissão de laudos.

Visão Geral

O fluxo para emissão de laudos veiculares segue 3 etapas:

graph LR
    A[1. Consulta Veicular] --> B[2. Selecionar Template]
    B --> C[3. Gerar Laudo]

1. Realizar uma consulta veicular - Primeiro você precisa ter uma consulta realizada
2. Selecionar o template de laudo - Escolha o modelo de laudo desejado
3. Gerar o laudo - Crie o laudo vinculando a consulta ao template

Templates de Laudo

Os templates definem o formato e as informações que serão incluídas no laudo.

Listar Templates Disponíveis

GET /vehicular-report-template

Headers obrigatórios:

Header	Descrição
Authorization	Bearer token JWT
x-organization-id	ID da organização

Resposta

{
  "statusCode": 200,
  "body": {
    "templates": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Laudo Completo",
        "description": "Laudo de vistoria completo com análise de todos os componentes",
        "status": "published",
        "externalReferenceId": "template-ref-001",
        "organizationId": "org-uuid",
        "ownerId": "owner-uuid",
        "productType": "VEHICULAR_REPORT"
      }
    ]
  }
}

Status dos Templates

Status	Descrição
draft	Template em rascunho (não disponível para uso)
published	Template publicado e disponível para uso

Criar Laudo a Partir de Consulta

Endpoint

POST /vehicular-report/create-from-query

Pré-requisitos

Antes de criar um laudo, você precisa:

1. ✅ Ter realizado uma consulta veicular (POST /queries/integration/:slug)
2. ✅ Ter o queryId da consulta realizada
3. ✅ Ter um template de laudo disponível

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
queryId	string	✅	ID da consulta veicular realizada
vehicularReportTemplateId	string	✅	ID do template de laudo

Exemplo de Requisição

curl -X POST "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/vehicular-report/create-from-query" \
  -H "Authorization: Bearer seu_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "queryId": "550e8400-e29b-41d4-a716-446655440000",
    "vehicularReportTemplateId": "123e4567-e89b-12d3-a456-426614174001"
  }'

Resposta

{
  "statusCode": 201,
  "body": {
    "vehicularReportId": "789e0123-e89b-12d3-a456-426614174002"
  }
}

Status do Laudo

Status	Descrição
draft	Laudo em processamento/elaboração
concluded	Laudo finalizado e disponível

Histórico de Laudos

Endpoint

GET /vehicular-report/history

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
page	number	❌	Número da página	1
limit	number	❌	Itens por página	25

Exemplo

curl -X GET "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/vehicular-report/history?page=1&limit=25" \
  -H "Authorization: Bearer seu_jwt_token"

Resposta

{
  "statusCode": 200,
  "body": {
    "reportHistory": {
      "docs": [
        {
          "id": "789e0123-e89b-12d3-a456-426614174002",
          "externalReferenceId": "report-ref-001",
          "queryId": "550e8400-e29b-41d4-a716-446655440000",
          "templateId": "123e4567-e89b-12d3-a456-426614174001",
          "templateName": "Laudo Completo",
          "organizationId": "org-uuid",
          "userId": "user-uuid",
          "status": "concluded",
          "createdAt": "2024-01-15T10:30:00Z",
          "updatedAt": "2024-01-15T10:35:00Z"
        }
      ],
      "totalDocs": 50,
      "totalPages": 2,
      "currentPage": 1,
      "limit": 25,
      "nextPage": 2,
      "hasNext": true
    }
  }
}

Resultado do Laudo

Os laudos veiculares podem conter informações como:

Categoria	Descrição
Parecer Técnico	Análise técnica do veículo
Indício de Sinistro	Verificação de sinistros anteriores
Histórico de Leilão	Informações sobre leilões
Score de Leilão	Pontuação relacionada a leilões
Diagnóstico do Veículo	Análise completa do estado
Histórico de KM	Registro de quilometragem
Análise Comparativa	Comparação com veículos similares

Tipos de Aprovação do Laudo

Aprovação	Descrição
approved	Veículo aprovado sem ressalvas
rejected	Veículo reprovado
approved_with_appointments	Aprovado com apontamentos
other	Outros casos

Tratamento de Erros

Erros Comuns

Código	Erro	Causa	Solução
400	MISSING_QUERY_ID	queryId não informado	Inclua o ID da consulta
400	MISSING_TEMPLATE_ID	Template não informado	Inclua o ID do template
404	QUERY_NOT_FOUND	Consulta não encontrada	Verifique o ID da consulta
404	TEMPLATE_NOT_FOUND	Template não encontrado	Verifique o ID do template
401	UNAUTHORIZED	Token inválido	Renove seu token JWT

Exemplo de Erro

{
  "statusCode": 404,
  "error": {
    "code": "QUERY_NOT_FOUND",
    "message": "A consulta informada não foi encontrada. Verifique o queryId."
  }
}

Fluxo Completo - Exemplo

1. Realizar Consulta Veicular

curl -X POST "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/queries/integration/consulta-completa-nacional" \
  -H "x-api-key: sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": {
      "licensePlate": "ABC1234"
    }
  }'

Resposta

{
  "statusCode": 201,
  "body": {
    "queryId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED"
  }
}

2. Listar Templates de Laudo

curl -X GET "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/vehicular-report-template" \
  -H "Authorization: Bearer seu_jwt_token" \
  -H "x-organization-id: sua_organization_id"

3. Criar Laudo

curl -X POST "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/vehicular-report/create-from-query" \
  -H "Authorization: Bearer seu_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "queryId": "550e8400-e29b-41d4-a716-446655440000",
    "vehicularReportTemplateId": "123e4567-e89b-12d3-a456-426614174001"
  }'

4. Consultar Histórico

curl -X GET "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/vehicular-report/history?page=1&limit=10" \
  -H "Authorization: Bearer seu_jwt_token"

Exemplos de Integração

Node.js com TypeScript

import axios from 'axios';

interface VehicularReportInput {
  queryId: string;
  vehicularReportTemplateId: string;
}

interface VehicularReportResult {
  vehicularReportId: string;
}

interface ReportHistoryParams {
  page?: number;
  limit?: number;
}

class ChecktudoReportClient {
  private baseUrl = 'https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo';
  
  constructor(
    private jwtToken: string,
    private organizationId: string,
  ) {}

  async listTemplates(): Promise<any[]> {
    const response = await axios.get(
      `${this.baseUrl}/vehicular-report-template`,
      {
        headers: {
          'Authorization': `Bearer ${this.jwtToken}`,
          'x-organization-id': this.organizationId,
        },
      }
    );
    return response.data.body.templates;
  }

  async createReport(input: VehicularReportInput): Promise<VehicularReportResult> {
    const response = await axios.post(
      `${this.baseUrl}/vehicular-report/create-from-query`,
      input,
      {
        headers: {
          'Authorization': `Bearer ${this.jwtToken}`,
          'Content-Type': 'application/json',
        },
      }
    );
    return response.data.body;
  }

  async getReportHistory(params: ReportHistoryParams = {}): Promise<any> {
    const { page = 1, limit = 25 } = params;
    const response = await axios.get(
      `${this.baseUrl}/vehicular-report/history`,
      {
        params: { page, limit },
        headers: {
          'Authorization': `Bearer ${this.jwtToken}`,
        },
      }
    );
    return response.data.body.reportHistory;
  }
}

// Uso
const client = new ChecktudoReportClient('seu_jwt_token', 'sua_organization_id');

async function main() {
  // 1. Listar templates disponíveis
  const templates = await client.listTemplates();
  console.log('Templates disponíveis:', templates);

  // 2. Criar laudo a partir de uma consulta
  const { vehicularReportId } = await client.createReport({
    queryId: '550e8400-e29b-41d4-a716-446655440000',
    vehicularReportTemplateId: templates[0].id,
  });
  console.log('Laudo criado:', vehicularReportId);

  // 3. Consultar histórico
  const history = await client.getReportHistory({ page: 1, limit: 10 });
  console.log('Histórico de laudos:', history);
}

main();

Boas Práticas

1. Cache de templates: Os templates raramente mudam, faça cache da listagem
2. Verificar status da consulta: Certifique-se que a consulta está COMPLETED antes de criar o laudo
3. Acompanhar processamento: Monitore o status do laudo até concluded

Próximos Passos

• Consultas Veiculares
• CRLV Digital
• Consultas em Lote