README

Pacote Laravel que integra um software com a API de chaves do finatto-financeiro (https://financeiro.steersync.com.br). Ele ativa a chave, valida uma vez por dia, confere a assinatura do JWT e guarda tudo no banco da aplicação.

Laravel 12 ou 13, PHP 8.2+ com ext-sodium. Não há arquivo de configuração.

Instalar

composer require finatto/license-client
php artisan migrate

A migration cria a tabela finatto_keys, com uma linha por dono da chave. No steersync, o dono é o workspace. Cada linha guarda a chave, o CNPJ, a instância, o último token e o JWKS.

Configurar em código

No AppServiceProvider::boot(), informe o token do software, criado em Integrações no financeiro, e o model dono da chave:

use App\Models\Workspace;
use Finatto\LicenseClient\Facades\FinattoKey;

FinattoKey::configure('fnt_...', Workspace::class);

FinattoKey::reportUsing(fn (Workspace $workspace): array => [
    'units' => $workspace->companies()->count(),
    'active_users' => $workspace->members()->where('status', 'active')->count(),
]);

reportUsing é opcional. Os valores chegam na tela de Saúde da chave. Para apontar para outro ambiente, passe a URL: FinattoKey::configure('fnt_...', Workspace::class, 'http://localhost:8000').

Ativar

O suporte ativa uma vez por workspace, com a chave e o CNPJ do cliente no financeiro:

php artisan finatto-key:activate 12 FNTCH-7K2MQ-9XHTD 66419483000171

Ou pela aplicação, numa tela própria:

FinattoKey::for($workspace)->activate($serial, $cnpj);

A instância é host do APP_URL/workspace-{id}. Use --instance= ou o terceiro argumento para trocar.
Chave de desenvolvimento não tem CNPJ: php artisan finatto-key:activate 12 FNTCH-....
Ativar de novo no mesmo workspace é seguro. A mesma chave em outro workspace recebe instance_conflict.
Se uma nova ativação for recusada, a ativação anterior do workspace continua valendo.

Usar

$key = FinattoKey::for($workspace);

$key->isUsable();                       // estado active ou expiring
$key->hasModule('vehicles');            // em qualquer produto da chave
$key->hasModule('vehicles', 'frota');   // num produto específico
$key->feature('policy-password', false);
$key->allowsUnits($workspace->companies()->count() + 1);   // antes de criar empresa, filial ou unidade
$key->allowsUsers($activeUsers);

$payload = $key->payload();

$payload->state;          // KeyState::Active, Expiring, AwaitingActivation, BlockedExpired, BlockedManual
$payload->blockReason;
$payload->validUntil;
$payload->accessLimit;    // usuários ativos. null = sem limite
$payload->unitsLimit;     // empresas, filiais e unidades. null = sem limite
$payload->isDevelopment();
$payload->client;         // id, legal_name, trade_name, document. null em chave de desenvolvimento
$payload->modules;        // ['frota' => ['vehicles', 'drivers']]
$payload->features;

isUsable, hasModule, feature, allowsUnits e allowsUsers nunca lançam exceção. Sem chave válida, eles negam ou devolvem o padrão. payload() lança KeyException, com o código em $exception->error.

A API não decide nada. Chave bloqueada chega como bloqueada, e o software decide o que fazer com o estado, os módulos, os limites e o ambiente.

Validação e falhas

O pacote agenda finatto-key:validate todo dia às 03:17 para todas as chaves ativadas. Basta o scheduler do Laravel estar rodando.
payload() também revalida sozinho quando o token tem mais de 24 h.
Se a API não responder, o último token segue valendo até o exp, que é de 48 h. A nova tentativa acontece no máximo uma vez por hora por workspace.
Se a API responder key_not_found, instance_conflict ou not_activated, o token do workspace é apagado. O workspace precisa de nova ativação.

Comandos

Comando	Uso
`finatto-key:activate {owner} {key} {document?} {--instance=}`	Ativa a chave de um workspace
`finatto-key:validate`	Valida agora todas as chaves ativadas
`finatto-key:status`	Lista as chaves do banco sem chamar a API

Desenvolvimento

composer install
composer check

finatto / license-client

Package info

Security

Statistics