Skip to main content
Este guia leva você do zero ao envio do primeiro CT-e de teste usando o SUOT Fiscal SDK para PHP. Você vai configurar o registry Composer privado, instalar os pacotes essenciais, declarar as credenciais da empresa e construir o seu primeiro Command. Todo o processo pode ser concluído em menos de 15 minutos em um ambiente local já preparado.
Pré-requisitos antes de começar:
  • PHP 8.4 ou superior instalado e disponível no PATH
  • Composer 2 instalado globalmente
  • Acesso ao Developer Portal com uma organização ativa
  • Token Composer gerado para o seu usuário (você vai gerar um no Passo 2)
1

Acesse o Developer Portal e crie uma organização

Acesse developers.suot.dev e faça login. Se ainda não tiver uma organização, crie uma — a organização é a titular da licença e o ponto de partida para emitir tokens Composer.Após criar a organização, certifique-se de que há uma licença do Fiscal SDK associada a ela. Sem uma licença ativa, o registry irá rejeitar as requisições de download dos pacotes.
Veja o guia completo em Organizações para entender papéis, membros e associação de licenças.
2

Gere um token Composer

No Developer Portal, navegue até a seção de tokens da sua organização e gere um token Composer pessoal. Copie o valor gerado — ele será exibido apenas uma vez.
Nunca inclua o token diretamente em arquivos versionados (composer.json, auth.json commitado, .env commitado). Nunca o registre em logs de aplicação ou de CI/CD. Se o token for exposto acidentalmente, revogue-o imediatamente no Developer Portal e emita um novo.
Para gerenciar tokens depois, acesse platform/tokens-composer.
3

Configure o registry no composer.json

Adicione o registry privado da SUOT ao composer.json do seu projeto. O Composer precisa saber onde buscar os pacotes suot/* antes de tentar o Packagist.
composer.json
{
  "repositories": [
    {
      "type": "composer",
      "url": "https://packages.suot.dev"
    }
  ],
  "require": {}
}
Em seguida, configure a autenticação via variável de ambiente. Nunca coloque o token diretamente no composer.json.
export COMPOSER_AUTH='{"http-basic":{"packages.suot.dev":{"username":"token","password":"SEU_TOKEN_AQUI"}}}'
Substitua SEU_TOKEN_AQUI pelo token gerado no passo anterior. Em pipelines de CI/CD, defina COMPOSER_AUTH como variável de ambiente secreta na plataforma de CI.
Se preferir usar auth.json localmente, certifique-se de adicioná-lo ao .gitignore. Veja detalhes em Tokens Composer.
4

Instale os pacotes do Fiscal SDK

Com o registry configurado e a autenticação disponível, instale os pacotes necessários para emitir CT-e:
composer require suot/fiscal-core suot/fiscal-sefaz suot/fiscal-cte
  • suot/fiscal-core — tipos base, Value Objects, interfaces e contratos do SDK
  • suot/fiscal-sefaz — comunicação com os webservices da SEFAZ
  • suot/fiscal-cte — commands, handlers e schemas específicos de CT-e
O Composer resolverá as dependências entre os pacotes automaticamente. Nenhuma configuração adicional de autoload é necessária além do padrão PSR-4 já gerenciado pelo Composer.
5

Configure as credenciais da empresa

Antes de construir o primeiro Command, informe os dados da empresa emitente. Em um projeto framework-agnostic, você instancia a configuração diretamente:
<?php

use Suot\Fiscal\Core\Config\EmpresaConfig;
use Suot\Fiscal\Core\Config\AmbienteConfig;
use Suot\Fiscal\Core\ValueObject\Cnpj;
use Suot\Fiscal\Core\ValueObject\CaminhoArquivo;

$empresa = new EmpresaConfig(
    cnpj: new Cnpj('00000000000000'),             // CNPJ da empresa (somente dígitos)
    razaoSocial: 'Transportadora Exemplo Ltda',
    certificadoPath: new CaminhoArquivo('/path/para/certificado.pfx'),
    certificadoSenha: 'senha-do-certificado',      // use variável de ambiente em produção
);

$ambiente = AmbienteConfig::homologacao();
Nunca inclua senhas de certificados diretamente no código-fonte. Em produção, use variáveis de ambiente ou um gerenciador de segredos. Os valores acima são apenas ilustrativos.
6

Construa e envie um Command de CT-e

Com a configuração em mãos, construa o Command de autorização, passe ao Handler e aguarde o Result:
<?php

use Suot\Fiscal\Cte\Command\AutorizarCteCommand;
use Suot\Fiscal\Cte\Handler\AutorizarCteHandler;
use Suot\Fiscal\Core\ValueObject\Cnpj;
use Suot\Fiscal\Core\ValueObject\Cep;
use Suot\Fiscal\Core\ValueObject\Valor;
use Suot\Fiscal\Core\ValueObject\Peso;

// Construa o Command com named arguments — totalmente tipado
$command = new AutorizarCteCommand(
    empresaConfig: $empresa,
    ambienteConfig: $ambiente,
    tomador: new Cnpj('11111111000100'),           // CNPJ do tomador (placeholder)
    remetente: new Cnpj('22222222000100'),         // CNPJ do remetente (placeholder)
    destinatario: new Cnpj('33333333000100'),      // CNPJ do destinatário (placeholder)
    cepOrigem: new Cep('01310-100'),
    cepDestino: new Cep('20040-020'),
    valorCarga: new Valor(1500.00),
    pesoBruto: new Peso(200.0),
);

// Instancie o Handler (ou receba por injeção de dependência)
$handler = new AutorizarCteHandler();

// Execute — retorna um Result, nunca lança exceção por rejeição esperada
$result = $handler->handle($command);
7

Inspecione o Result

O Handler retorna sempre um objeto Result tipado. Rejeições esperadas pela SEFAZ são representadas como resultado — não como exceção. Falhas técnicas de infraestrutura lançam InfrastructureException.
<?php

use Suot\Fiscal\Core\Result\ResultStatus;

if ($result->isSuccess()) {
    // CT-e autorizado com sucesso
    echo 'Chave de acesso: ' . $result->chaveAcesso()->valor();
    echo 'Protocolo: ' . $result->protocolo()->numero();
    echo 'XML autorizado disponível em: ' . $result->xmlPath()->valor();
} else {
    // Rejeição retornada pela SEFAZ — trate com a lógica de negócio adequada
    echo 'Rejeição: ' . $result->codigoRejeicao()->valor();
    echo 'Motivo: ' . $result->motivoRejeicao();
}
Em ambiente de homologação, a SEFAZ pode retornar rejeições específicas para dados de teste. Consulte o Guia de Homologação para configurar cenários de teste corretamente.
Antes de ir para produção, complete o ambiente de homologação: configure certificado digital de teste (emitido pela ICP-Brasil para homologação), valide o schema XML e teste os principais cenários de rejeição. Veja o passo a passo em Guia de Homologação.
Para gerenciar, renovar ou revogar tokens Composer — incluindo tokens de CI/CD —, acesse Tokens Composer.