README

SDK PHP 8.2+ 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.

TODAS as funções são geradas dinamicamente via __call. Nenhuma função é declarada diretamente na classe.

Características

• ✅ 100% __call-based: Zero funções hardcoded - tudo vem do Postman
• ✅ Slug-based API: Chamadas simples via $client->veiculos_agregados()
• ✅ Modo Sandbox: Teste sem conexão com a API real
• ✅ 177 endpoints: Gerados automaticamente da coleção Postman
• ✅ CLI Completo: Liste endpoints disponíveis
• ✅ PHP 8.2+: Usa recursos modernos do PHP (readonly, match, enums)
• ✅ PSR-4: Autoloading compatível com Composer
• ✅ PHPUnit: Testes automatizados

📦 Instalação

composer require consultasdeveiculos/sdk

Após a instalação, o script postinstall.php baixa automaticamente a coleção Postman.

🏁 Início Rápido

<?php

require 'vendor/autoload.php';

use Consultasdeveiculos\SDK\Core\SDK as ConsultadeveiculosSDK;

// Modo Produção
$client = new ConsultadeveiculosSDK([
    'auth_token' => 'SEU_TOKEN'
]);

// Consultar veículo
$resultado = $client->veiculos_agregados(['placa' => 'ABC1234']);
echo $resultado['data']['modelo']; // Modelo do veículo

🧪 Modo Sandbox

// Modo Sandbox - sem token, sem requisições reais
$client = new ConsultadeveiculosSDK(['sandbox' => true]);

// Retorna respostas simuladas do Postman
$resultado = $client->veiculos_agregados(['placa' => 'ABC1234']);
// $resultado['sandbox'] === true

📡 Como Funciona

1. A SDK carrega a coleção Postman (arquivo JSON)
2. Parseia todos os endpoints e gera slugs baseados nas URLs
3. Via __call, qualquer chamada de método é interceptada
4. O slug é mapeado para o endpoint correto
5. A requisição é enviada com os parâmetros fornecidos

Formato do Slug

URL do endpoint           →  Slug (método PHP)
───────────────────────────────────────────────────
/veiculos/agregados       →  $client->veiculos_agregados()
/veiculos/debitos-sp      →  $client->veiculos_debitos_sp()
/cnh/nacional-simples     →  $client->cnh_nacional_simples()
/credito/score-pf         →  $client->credito_score_pf()

🔧 Métodos Auxiliares

$client->help();              // Exibe ajuda completa
$client->help('veiculos');    // Filtra endpoints por termo
$client->endpoints();         // Lista todos os endpoints
$client->info();              // Informações do SDK
$client->search('placa');     // Busca endpoints

// Métodos sem output no console
$client->getInfo();           // Retorna array com informações
$client->listEndpoints();     // Retorna array com todos os endpoints
$client->listSlugs();         // Retorna array com todos os slugs
$client->searchEndpoints('x');// Busca endpoints por padrão

🖥️ CLI

# Lista todos os endpoints
./vendor/bin/consultasdeveiculos-sdk endpoints

# Filtra por namespace
./vendor/bin/consultasdeveiculos-sdk endpoints veiculos

# Atualiza a especificação
./vendor/bin/consultasdeveiculos-sdk update

# Versão
./vendor/bin/consultasdeveiculos-sdk version

# Diagnóstico
./vendor/bin/consultasdeveiculos-sdk doctor

# Limpa cache
./vendor/bin/consultasdeveiculos-sdk clear-cache --force

⚠️ Tratamento de Erros

use Consultasdeveiculos\SDK\Errors\AuthenticationError;
use Consultasdeveiculos\SDK\Errors\ValidationError;
use Consultasdeveiculos\SDK\Errors\RateLimitError;
use Consultasdeveiculos\SDK\Errors\EndpointNotFoundError;
use Consultasdeveiculos\SDK\Errors\SDKError;

try {
    $result = $client->veiculos_agregados(['placa' => 'ABC1234']);
} catch (AuthenticationError $e) {
    // Token inválido ou expirado
} catch (ValidationError $e) {
    // Parâmetros inválidos
} catch (RateLimitError $e) {
    // Limite de requisições - espere $e->retryAfter segundos
} catch (EndpointNotFoundError $e) {
    // Slug não existe
} catch (SDKError $e) {
    // Erro genérico da SDK
    echo $e->code;      // Código do erro
    echo $e->details;   // Detalhes adicionais
    echo $e->timestamp; // Timestamp ISO
}

🏗️ Arquitetura

src/
├── Core/
│   ├── SDK.php              ← Entry point, lógica central com __call
│   ├── ConfigManager.php    ← Gerenciamento de configuração e cache
│   ├── EndpointBuilder.php  ← Construção da API dinâmica
│   ├── EndpointRegistry.php ← Registro de endpoints
│   └── PostmanLoader.php    ← Carregamento da coleção Postman
├── Transport/
│   ├── Transport.php        ← Interface base
│   ├── HttpTransport.php    ← HTTP real (Guzzle)
│   └── SandboxTransport.php ← Respostas simuladas
├── Parser/
│   ├── PostmanParser.php    ← Parser principal
│   ├── FolderParser.php     ← Parser de pastas/namespaces
│   └── RequestParser.php    ← Parser de requisições
├── Errors/
│   ├── SDKError.php
│   ├── AuthenticationError.php
│   ├── ValidationError.php
│   ├── RateLimitError.php
│   ├── EndpointNotFoundError.php
│   └── SpecificationError.php
├── Cli/
│   ├── EndpointsCommand.php
│   ├── UpdateCommand.php
│   ├── VersionCommand.php
│   ├── DoctorCommand.php
│   └── ClearCacheCommand.php
└── Cache/
    └── (placeholder)

🔒 Segurança

• Token armazenado em propriedade privada
• Dados sensíveis sanitizados em mensagens de erro
• Sem exposição de stack traces em produção
• HTTPS obrigatório

🧪 Testes

composer test

📋 Requisitos

• PHP >= 8.2
• ext-curl
• ext-json
• ext-mbstring
• ext-intl

📄 Licença

MIT