ConsultasDeVeiculos.SDK 1.0.3

ConsultasDeVeiculos SDK (.NET)

SDK .NET dinâmica para consultas de veículos, baseada em coleções Postman.

🚀 Visão Geral

Esta SDK funciona como um Runtime Engine que consome endpoints definidos em uma coleção Postman, sem necessidade de implementação manual de cada endpoint.

Endpoints são gerados dinamicamente a partir da coleção Postman.

Características

• ✅ 100% Cross-platform: Windows, Linux e macOS
• ✅ Slug-based API: Chamadas simples via client.ExecuteAsync("veiculos_agregados")
• ✅ Dynamic support: Use dynamic para chamadas similares ao JavaScript
• ✅ Modo Sandbox: Teste sem conexão com a API real
• ✅ 177 endpoints: Gerados automaticamente da coleção Postman
• ✅ CLI Completo: Liste endpoints disponíveis
• ✅ .NET 10: Última versão do .NET

📦 Instalação

Via NuGet

dotnet add package ConsultasDeVeiculos.SDK

CLI Tool

dotnet tool install -g ConsultasDeVeiculos.SDK.Cli

🏁 Início Rápido

Configuração via .env

Copie o arquivo .env.example para .env e configure:

cp .env.example .env

# Token de autenticação da API (obrigatório em produção)
API_TOKEN=SEU_TOKEN_AQUI

# URL de download do postman.json (opcional)
DOWNLOAD_URL=https://painel.consultasdeveiculos.com/download-postman

# URL base da API (opcional)
API_BASE_URL=https://api.consultasdeveiculos.com

# Timeout das requisições em ms (opcional - padrão: 30000)
# API_TIMEOUT=30000

# Número máximo de retries (opcional - padrão: 3)
# API_MAX_RETRIES=3

Então use:

using ConsultasDeVeiculos.SDK;

// Carrega .env automaticamente e cria o client
var client = ConsultadeveiculosSDK.FromEnv();

var resultado = await client.ExecuteAsync("veiculos_agregados", new Dictionary<string, object?>
{
    ["placa"] = "ABC1234"
});

Modo Produção (via código)

using ConsultasDeVeiculos.SDK;
using ConsultasDeVeiculos.SDK.Core;

// Inicializa com token obrigatório
var client = new ConsultadeveiculosSDK(new SDKOptions
{
    AuthToken = "SEU_TOKEN_AQUI"
});

// Consulta usando o slug do endpoint
var resultado = await client.ExecuteAsync("veiculos_agregados", new Dictionary<string, object?>
{
    ["placa"] = "ABC1234"
});

Console.WriteLine(resultado.Data);

Modo Sandbox

using ConsultasDeVeiculos.SDK;
using ConsultasDeVeiculos.SDK.Core;

// Via .env (modo sandbox)
var client = ConsultadeveiculosSDK.FromEnvSandbox();

// Ou via código
var client = new ConsultadeveiculosSDK(new SDKOptions
{
    Sandbox = true
});

// As chamadas retornam respostas simuladas
var resultado = await client.ExecuteAsync("veiculos_agregados", new Dictionary<string, object?>
{
    ["placa"] = "ABC1234"
});

Console.WriteLine(resultado.Data); // Resposta de exemplo do Postman

Híbrido: .env + opções manuais

using ConsultasDeVeiculos.SDK;
using ConsultasDeVeiculos.SDK.Core;

// Carrega .env para variáveis de ambiente
DotEnv.Load();

// Cria options a partir do .env e complementa
var options = DotEnv.CreateOptionsFromEnvironment();
options.Timeout = 60000;  // Sobrescreve timeout

var client = new ConsultadeveiculosSDK(options);

Usando Dynamic (similar ao JavaScript)

var client = new ConsultadeveiculosSDK(new SDKOptions { Sandbox = true });
dynamic sdk = client.AsDynamic();

// Chamada idêntica ao JavaScript
var resultado = await sdk.veiculos_agregados(new { placa = "ABC1234" });
Console.WriteLine(resultado.Status);

Usando Indexador

var client = new ConsultadeveiculosSDK(new SDKOptions { Sandbox = true });

var resultado = await client["veiculos_debitos_sp"].ExecuteAsync(new Dictionary<string, object?>
{
    ["placa"] = "ABC1234"
});

📖 API

Inicialização

// OPÇÃO 1: Via .env (recomendado)
var client = ConsultadeveiculosSDK.FromEnv();

// OPÇÃO 2: Via código
var client = new ConsultadeveiculosSDK(new SDKOptions
{
    AuthToken = "TOKEN",      // Obrigatório em produção
    Sandbox = false,          // Modo sandbox (padrão: false)
    BaseUrl = "URL",          // URL base customizada (opcional)
    Timeout = 30000,          // Timeout em ms (padrão: 30000)
    MaxRetries = 3            // Máximo de retries (padrão: 3)
});

Variáveis de Ambiente (.env)

Como Chamar Endpoints

O slug é derivado da URL do endpoint, substituindo / e - por _:

Métodos Disponíveis

Tratamento de Erros

using ConsultasDeVeiculos.SDK.Errors;

try
{
    var result = await client.ExecuteAsync("veiculos_agregados", params);
}
catch (AuthenticationException ex)
{
    // Token inválido ou expirado
}
catch (ValidationException ex)
{
    // Dados de entrada inválidos
}
catch (RateLimitException ex)
{
    // Rate limit - aguardar ex.RetryAfter segundos
}
catch (EndpointNotFoundException ex)
{
    // Slug não encontrado
}
catch (SDKException ex)
{
    // Outro erro genérico da SDK
}

🖥️ CLI

# Lista todos os endpoints
consultas-de-veiculos-sdk endpoints

# Filtra endpoints
consultas-de-veiculos-sdk endpoints veiculos

# Com descrições
consultas-de-veiculos-sdk endpoints --verbose

# Versão
consultas-de-veiculos-sdk version

# Diagnóstico
consultas-de-veiculos-sdk doctor

# Atualizar especificação
consultas-de-veiculos-sdk update

# Limpar cache
consultas-de-veiculos-sdk clear-cache

🏗️ Estrutura do Projeto

ConsultasDeVeiculos.SDK/
├── src/
│   ├── ConsultasDeVeiculos.SDK/           # Biblioteca principal
│   │   ├── Core/                          # Classes core (Models, Config, Registry)
│   │   ├── Transport/                     # Camada de transporte (HTTP, Sandbox)
│   │   ├── Parser/                        # Parsers de coleção Postman
│   │   ├── Errors/                        # Exceções tipadas
│   │   ├── ConsultadeveiculosSDK.cs       # Classe principal
│   │   └── DynamicSDK.cs                  # Wrapper dinâmico
│   └── ConsultasDeVeiculos.SDK.Cli/       # Ferramenta CLI
├── tests/
│   └── ConsultasDeVeiculos.SDK.Tests/     # Testes unitários (xUnit)
├── examples/                              # Exemplos de uso
├── spec/                                  # Especificação Postman
└── ConsultasDeVeiculos.SDK.sln            # Solution

🔧 Desenvolvimento

Pré-requisitos

• .NET 10 SDK ou superior

Build

dotnet build

Testes

dotnet test

Executar CLI

dotnet run --project src/ConsultasDeVeiculos.SDK.Cli -- endpoints

📋 Compatibilidade

📄 Licença

MIT - DATACUBE SERVICO DE INFORMACAO VIA WEB LTDA