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

A SDK carrega a coleção Postman (arquivo JSON)
Parseia todos os endpoints e gera slugs baseados nas URLs
Via __call, qualquer chamada de método é interceptada
O slug é mapeado para o endpoint correto
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

// 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

consultasdeveiculos / sdk

Maintainers

Package info

Statistics

Security