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://hwfxu4zs36.execute-api.sa-east-1.amazonaws.com/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://hwfxu4zs36.execute-api.sa-east-1.amazonaws.com/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://hwfxu4zs36.execute-api.sa-east-1.amazonaws.com/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​