Pular para o conteúdo principal

Consultas em Lote

As consultas em lote permitem processar milhares de consultas veiculares de uma vez, através do upload de arquivos CSV ou XLSX.

Visão Geral​

Ideal para:

  • 📊 Empresas com grandes frotas
  • 🏢 Lojas de veículos
  • 🔄 Processos de due diligence em massa
  • 📈 Análises de portfólio

Fluxo de Processamento​

graph LR
    A[1. Upload Arquivo] --> B[2. Validação]
    B --> C[3. Processamento]
    C --> D[4. Download Resultado]

Submeter Consulta em Lote​

Endpoint​

POST /batch-queries/submit

Headers​

HeaderTipoObrigatórioDescrição
AuthorizationBearer Token✅Token JWT de autenticação
Content-Typemultipart/form-data✅Tipo de conteúdo

Parâmetros​

ParâmetroTipoObrigatórioDescrição
fileFile✅Arquivo CSV ou XLSX com as placas
batchQueryTemplateIdstring✅ID do template de lote

Formato do Arquivo​

O arquivo deve conter uma coluna com as placas dos veículos:

placa
ABC1234
DEF5678
GHI9012

Exemplo​

curl -X POST "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/batch-queries/submit" \
  -H "Authorization: Bearer seu_jwt_token" \
  -F "file=@consultas.csv" \
  -F "batchQueryTemplateId=template-uuid"

Resposta​

{
  "statusCode": 201,
  "body": {
    "batchQueryId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PROCESSING",
    "totalItems": 150
  }
}

Listar Consultas em Lote​

Endpoint​

GET /batch-queries

Parâmetros de Query​

ParâmetroTipoObrigatórioDescrição
pagenumber❌Número da página
limitnumber❌Itens por página

Exemplo​

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

Resposta​

{
  "statusCode": 200,
  "body": {
    "docs": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "status": "COMPLETED",
        "totalItems": 150,
        "processedItems": 150,
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "totalDocs": 10,
    "totalPages": 1,
    "currentPage": 1
  }
}

Status do Processamento​

StatusDescrição
PENDINGAguardando processamento
PROCESSINGEm processamento
COMPLETEDConcluído com sucesso
FAILEDFalha no processamento
PARTIALConcluído parcialmente

Download do Resultado​

Endpoint​

GET /batch-queries/:batchQueryId/file

Exemplo​

curl -X GET "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/batch-queries/550e8400-e29b-41d4-a716-446655440000/file" \
  -H "Authorization: Bearer seu_jwt_token" \
  -o resultado.xlsx

O arquivo de resultado contém todas as colunas do arquivo original mais os dados da consulta.

Templates de Lote​

Listar Templates​

GET /batch-query-templates
{
  "statusCode": 200,
  "body": {
    "templates": [
      {
        "id": "template-uuid",
        "name": "Consulta Básica em Lote",
        "description": "Dados básicos do veículo",
        "pricePerItem": 3.50
      }
    ]
  }
}

Limites​

RecursoLimite
Tamanho máximo do arquivo10 MB
Itens por arquivo10.000
Consultas simultâneas3

Tratamento de Erros​

Erros Comuns​

CódigoErroCausaSolução
400INVALID_FILE_FORMATFormato não suportadoUse CSV ou XLSX
400FILE_TOO_LARGEArquivo muito grandeDivida em arquivos menores
400TOO_MANY_ITEMSMuitos itensLimite de 10.000 itens
402INSUFFICIENT_BALANCESaldo insuficienteAdicione créditos

Boas Práticas​

  1. Validação prévia: Valide as placas antes do upload
  2. Monitoramento: Verifique o status periodicamente
  3. Arquivos menores: Divida arquivos grandes para processamento mais rápido
  4. Backup: Guarde uma cópia do arquivo original

Próximos Passos​