Skip to main content
O SUOT Fiscal SDK é distribuído exclusivamente pelo registry privado packages.suot.dev e requer autenticação com um token Composer vinculado à sua licença SUOT. O processo de instalação é padrão Composer, com um único passo adicional de configuração do repositório. Este guia cobre tudo que você precisa para ter o SDK funcionando em um projeto PHP do zero.

​
Pré-requisitos

Certifique-se de que o seu ambiente atende aos requisitos abaixo antes de iniciar a instalação:
  • PHP 8.4 ou superior — verifique com php -v
  • Composer 2 — verifique com composer -V (Composer 1 não é suportado)
  • Token Composer SUOT — gere o seu no painel em developers.suot.dev
  • Licença SUOT ativa — necessária para autenticar o acesso ao registry; gerencie suas licenças em developers.suot.dev
As extensões PHP openssl, soap, curl, mbstring e dom são necessárias em tempo de execução. A maioria dos ambientes de produção e desenvolvimento já as inclui por padrão.

​
Instalação passo a passo

1

Configure o registry privado

Adicione o repositório privado da SUOT ao composer.json do seu projeto. Se o arquivo ainda não existir, crie-o na raiz do projeto.
composer.json
{
  "repositories": [
    {
      "type": "composer",
      "url": "https://packages.suot.dev"
    }
  ]
}
Você também pode adicionar o repositório via linha de comando: composer config repositories.suot composer https://packages.suot.dev
2

Autentique com seu token Composer

Configure a autenticação com o token obtido em developers.suot.dev. A forma recomendada é via variável de ambiente, evitando que credenciais sejam gravadas em arquivos versionados.
export COMPOSER_AUTH='{"http-basic":{"packages.suot.dev":{"username":"token","password":"SEU_TOKEN_SUOT_AQUI"}}}'
Nunca comite credenciais no repositório. Substitua SEU_TOKEN_SUOT_AQUI pelo valor real apenas em ambientes seguros (CI/CD secrets, variáveis de ambiente do servidor). O arquivo auth.json local gerado pelo Composer também não deve ser versionado — adicione-o ao .gitignore.
Em pipelines de CI/CD, injete COMPOSER_AUTH como secret da plataforma (GitHub Actions, GitLab CI, etc.) em vez de armazená-lo em arquivos.
3

Instale os pacotes

Instale os pacotes de acordo com os documentos fiscais que o seu projeto precisa emitir. O pacote suot/fiscal-core e suot/fiscal-sefaz são dependências base obrigatórias para qualquer combinação.Somente CT-e:
composer require suot/fiscal-core suot/fiscal-sefaz suot/fiscal-cte
Somente MDF-e:
composer require suot/fiscal-core suot/fiscal-sefaz suot/fiscal-mdfe
CT-e e MDF-e juntos:
composer require suot/fiscal-core suot/fiscal-sefaz suot/fiscal-cte suot/fiscal-mdfe
O Composer resolverá as dependências e instalará os pacotes a partir do registry packages.suot.dev.
Em ambientes de produção, prefixe o comando com --no-dev e considere fixar a versão com o operador de compatibilidade (^) para garantir builds reproduzíveis. Consulte o painel SUOT para a versão atual disponível na sua licença.
4

Verifique a instalação

Após a instalação, confirme que o autoload do Composer consegue resolver as classes do SDK com um pequeno script de verificação:
verify.php
<?php

require_once __DIR__ . '/vendor/autoload.php';

use Suot\Fiscal\Core\ValueObjects\Cnpj;
use Suot\Fiscal\Sefaz\Environment;

echo 'SUOT Fiscal SDK instalado com sucesso.' . PHP_EOL;
echo 'Ambiente disponível: ' . Environment::Homologacao->value . PHP_EOL;
Execute com:
php verify.php
Se a saída exibir a mensagem de sucesso sem erros de autoload, a instalação está correta.

​
Laravel Bridge

Se o seu projeto usa Laravel, existe um pacote de integração dedicado que registra automaticamente o Service Provider, configura Facades e disponibiliza o arquivo config/fiscal.php: 
composer require suot/fiscal-laravel
O suot/fiscal-laravel depende dos demais pacotes fiscais. Instale-o em adição (não em substituição) aos pacotes de documento que você precisar. Consulte o guia completo em Laravel Bridge.

​
Fixar versões em produção

O SUOT Fiscal SDK está em Early Access e o versionamento semântico pode refletir mudanças de API entre versões menores durante este período. Para ambientes de produção, recomendamos fixar versões com o operador de compatibilidade (^) e revisar o changelog antes de atualizar.
Exemplo de restrição de versão no composer.json:
composer.json
{
  "require": {
    "suot/fiscal-core":   "^x.y",
    "suot/fiscal-sefaz":  "^x.y",
    "suot/fiscal-cte":    "^x.y"
  }
}
Substitua x.y pela versão disponível na sua licença. Consulte o painel em developers.suot.dev para verificar qual versão está liberada para o seu plano.

​
Próximos passos

Com os pacotes instalados, configure as credenciais do emitente, o certificado digital e o ambiente SEFAZ: