PHPackages                             fragososoftware/projecao-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. fragososoftware/projecao-sdk

ActiveLibrary[API Development](/categories/api)

fragososoftware/projecao-sdk
============================

SDK PHP para a API de Projeções Eleitorais (Fragoso Software). PHP puro, arquitetura hexagonal, compatível com PHP 7 e 8.

v1.0.0(today)00proprietaryPHPPHP ^7.0 || ^8.0

Since Jun 18Pushed todayCompare

[ Source](https://github.com/fsdrasfragoso/projecao-sdk-php)[ Packagist](https://packagist.org/packages/fragososoftware/projecao-sdk)[ Docs](https://fragososoftware.com)[ RSS](/packages/fragososoftware-projecao-sdk/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (2)Used By (0)

Projeção SDK (PHP)
==================

[](#projeção-sdk-php)

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

[](#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
------------

[](#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
---------------------

[](#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)
---------------------------------------------

[](#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
-------------------

[](#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
-----------

[](#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
------

[](#testes)

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

Licença
-------

[](#licença)

Proprietária — © Fragoso Software ().

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c04d1daa8802ea42c207c93b9bb336c1dfe758b7830a88f2ef2d91bf5377f859?d=identicon)[fsdrasfragoso](/maintainers/fsdrasfragoso)

---

Tags

apisdkprojecaoeleicoesfragososoftware

### Embed Badge

![Health badge](/badges/fragososoftware-projecao-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/fragososoftware-projecao-sdk/health.svg)](https://phpackages.com/packages/fragososoftware-projecao-sdk)
```

###  Alternatives

[deepseek-php/deepseek-php-client

deepseek PHP client is a robust and community-driven PHP client library for seamless integration with the Deepseek API, offering efficient access to advanced AI and data processing capabilities.

46784.5k5](/packages/deepseek-php-deepseek-php-client)[jstolpe/instagram-graph-api-php-sdk

Instagram Graph API PHP SDK

138106.8k2](/packages/jstolpe-instagram-graph-api-php-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)