README

SDK oficial em PHP puro para a API de Projeções Eleitorais da Fragoso Software. Permite que seu portal/jornal/sistema monte sua própria calculadora e envie projeções.

• ✅ Compatível com PHP 7.0+ e 8.x (sem dependências além de ext-curl e ext-json)
• ✅ Arquitetura hexagonal (núcleo de domínio + portas + adaptadores)
• ✅ Enums/códigos encapsulados (Scope, Sphere, VotingType, Turn)
• ✅ Builder fluente para montar e enviar projeções
• ✅ Autenticação OAuth2 (client_credentials) gerenciada automaticamente

Instalação

Com Composer:

composer require fragososoftware/projecao-sdk

Sem Composer (basta incluir o autoloader que acompanha o pacote):

require __DIR__ . '/projecao-sdk-php/autoload.php';

Configuração

use Fragososoftware\ProjecaoSdk\ProjecaoSdk;

$client = ProjecaoSdk::create(
    'https://projecao.fragososoftware.com',
    'SEU_CLIENT_ID',
    'SEU_CLIENT_SECRET',
    array(
        // 'timeout' => 20,
        // 'origin'  => 'https://seuportal.com', // se sua aplicação tiver domínios cadastrados
        // 'http_client' => $seuAdaptador,        // injete seu próprio transporte (porta HttpClientInterface)
    )
);

O client_id/client_secret são gerados no painel admin em API → Aplicações. Se sua aplicação tiver domínios cadastrados, informe origin com um domínio liberado.

Enviando uma projeção

use Fragososoftware\ProjecaoSdk\Domain\Enum\Scope;
use Fragososoftware\ProjecaoSdk\Domain\Model\ProjectionRequest;
use Fragososoftware\ProjecaoSdk\Domain\Model\CandidateProjection;

$projecao = ProjectionRequest::make()
    ->setElectionId(5)
    ->setScope(Scope::ESTADO)            // regiao | estado | regiao_estado | municipio
    ->setExternalCode('MINHA-PESQUISA-123') // opcional; reenviar o mesmo código atualiza
    ->setAnalyst('João da Silva', 'joao@portal.com') // opcional
    ->addCandidate(
        CandidateProjection::make(3)->setUnit(12, 60)->setUnit(13, 40)
    )
    ->addCandidate(
        CandidateProjection::make(4)->setUnits(array(12 => 40, 13 => 60))
    );

$resultado = $client->sendProjection($projecao);   // persiste
// $resultado = $client->previewProjection($projecao); // calcula sem salvar

echo $resultado['total_votes'];
foreach ($resultado['ranking'] as $linha) {
    echo $linha['name'] . ': ' . $linha['percentage'] . "%\n";
}

A unidade (setUnit($unitId, $pct)) é o id de um estado, região, macrorregião ou município, conforme o scope. Use os endpoints de referência para obtê-los.

Endpoints de referência (para montar a grade)

$client->me();                              // dados da aplicação
$client->offices();                         // cargos disponíveis
$client->elections(array('political_office_id' => 4, 'state_id' => 7));
$client->election($id);                     // eleição + regras (escopos, turnos)
$client->states();                          // estados (inclui Exterior)
$client->units(Scope::ESTADO);              // unidades da projeção por escopo
$client->units(Scope::MUNICIPIO, $stateId); // (regiao_estado/municipio exigem estado)
$client->candidates(array('election_id' => 5));
$client->regions(array('include_municipalities' => 0));
$client->parties();
$client->spectrums();
$client->analysts();
$client->averages($electionId);            // média consolidada
$client->projections(array('election_id' => 5)); // suas projeções (data + meta)
$client->projection($id);                  // detalhe de uma projeção

Tratamento de erros

Todas as exceções estendem ProjecaoException:

use Fragososoftware\ProjecaoSdk\Domain\Exception\ValidationException;
use Fragososoftware\ProjecaoSdk\Domain\Exception\AuthenticationException;
use Fragososoftware\ProjecaoSdk\Domain\Exception\ApiException;
use Fragososoftware\ProjecaoSdk\Domain\Exception\ProjecaoException;

try {
    $client->sendProjection($projecao);
} catch (ValidationException $e) {
    // 422 ou validação local; $e->getErrors() => campo => mensagens
} catch (AuthenticationException $e) {
    // 401 (credenciais) ou 403 (domínio não autorizado)
} catch (ApiException $e) {
    // demais erros HTTP; $e->getStatusCode(), $e->getResponseData()
} catch (ProjecaoException $e) {
    // qualquer outro erro do SDK (inclui transporte/rede)
}

O builder também valida localmente antes de enviar (validate() é chamado por sendProjection/previewProjection), economizando uma ida ao servidor.

Arquitetura

Hexagonal (ports & adapters):

src/
  Domain/          Núcleo: Enum/ (códigos), Model/ (builder), Exception/
  Port/            Portas: HttpClientInterface (transporte) + HttpResponse
  Application/     Casos de uso: Configuration, TokenManager, Client (fachada)
  Infrastructure/  Adaptadores: Http/CurlHttpClient (implementa a porta)
  ProjecaoSdk.php  Composition root (wiring)

O núcleo depende apenas das portas. Para usar outro transporte (Guzzle, PSR-18), implemente Port\HttpClientInterface e passe via 'http_client'.

Testes

php tests/smoke.php   # sem rede (stub da porta HTTP)

Licença

Proprietária — © Fragoso Software (https://fragososoftware.com).