Skip to main content
O SUOT Fiscal SDK é framework-agnostic — funciona em qualquer projeto PHP 8.4+ sem nenhuma dependência de framework. O Laravel Bridge (suot/fiscal-laravel) é um pacote opcional que adiciona integração nativa ao Laravel: registro automático dos Handlers no container de injeção de dependência, publicação do arquivo de configuração config/suot-fiscal.php e leitura de credenciais a partir de variáveis de ambiente. Se você usa Laravel, o Bridge é a forma recomendada de integrar o SDK.

​
Pré-requisitos

Antes de instalar o Bridge, certifique-se de que você possui:
  • Laravel 10.x ou 11.x
  • PHP 8.4 ou superior
  • Pacotes do Fiscal SDK já instalados via Composer (suot/fiscal-core e os pacotes de documentos desejados, como suot/fiscal-cte e suot/fiscal-mdfe)
  • Certificado digital A1 (arquivo .pfx) do emitente em local acessível pela aplicação
Ainda não instalou o Fiscal SDK? Consulte Instalação para configurar o registry Composer da SUOT e instalar os pacotes base.

​
Instalação

1

Instalar o pacote Bridge via Composer

Execute o comando abaixo na raiz do seu projeto Laravel:
composer require suot/fiscal-laravel
O Laravel detecta automaticamente o SuotFiscalServiceProvider via package auto-discovery — nenhuma entrada manual em config/app.php é necessária.
2

Publicar o arquivo de configuração

Publique o arquivo de configuração para o diretório config/ da sua aplicação:
php artisan vendor:publish --tag=suot-fiscal-config
Isso criará o arquivo config/suot-fiscal.php com todas as opções disponíveis e valores padrão. Você pode inspecionar e ajustar o arquivo a qualquer momento.
3

Configurar as variáveis de ambiente

Adicione as variáveis abaixo ao seu arquivo .env. Use valores reais apenas em produção — para desenvolvimento e testes, utilize o ambiente homologacao.
# Ambiente da SEFAZ: homologacao | producao
SUOT_FISCAL_ENV=homologacao

# CNPJ do emitente (somente dígitos)
SUOT_FISCAL_CNPJ=12345678000199

# Caminho absoluto ou relativo (a partir de storage_path()) para o certificado PFX
SUOT_FISCAL_CERT_PATH=/var/www/certs/certificado-empresa.pfx

# Senha do certificado PFX — nunca comite este valor no repositório
SUOT_FISCAL_CERT_PASSWORD=senha_do_certificado

# Código do autorizador SEFAZ: SP, SVCAN, SVCRS, RS, MG, etc.
SUOT_FISCAL_AUTHORIZER=SP
Nunca comite o valor de SUOT_FISCAL_CERT_PASSWORD no repositório. Use .env local para desenvolvimento e um gerenciador de segredos (AWS Secrets Manager, Vault, etc.) em produção.
4

Usar injeção de dependência nos seus controllers ou services

Após a instalação, todos os Handlers registrados pelo Bridge estão disponíveis para injeção automática pelo container do Laravel.
<?php

namespace App\Services;

use Suot\Fiscal\CTe\Handler\EmitirCTeHandler;
use Suot\Fiscal\CTe\Command\EmitirCTeCommand;
use Suot\Fiscal\CTe\Result\EmitirCTeResult;
use Suot\Fiscal\Exception\InfrastructureException;

final class EmissaoCTeService
{
    public function __construct(
        private readonly EmitirCTeHandler $emitirCTeHandler,
    ) {}

    public function emitir(EmitirCTeCommand $command): EmitirCTeResult
    {
        try {
            return $this->emitirCTeHandler->handle($command);
        } catch (InfrastructureException $e) {
            // Registre e relance ou trate conforme a lógica da sua aplicação
            logger()->critical('Falha de infraestrutura ao emitir CT-e', [
                'mensagem' => $e->getMessage(),
            ]);
            throw $e;
        }
    }
}
Em um controller, a injeção funciona da mesma forma:
<?php

namespace App\Http\Controllers;

use App\Services\EmissaoCTeService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

final class CTeController extends Controller
{
    public function __construct(
        private readonly EmissaoCTeService $service,
    ) {}

    public function emitir(Request $request): JsonResponse
    {
        // Construa o command a partir dos dados validados da request
        // $command = CTeBuilder::novo()->...->build();

        $result = $this->service->emitir($command);

        if ($result->isSuccess()) {
            return response()->json([
                'chave'     => (string) $result->getChave(),
                'protocolo' => (string) $result->getProtocolo(),
            ]);
        }

        return response()->json([
            'rejeicao' => $result->getRejeicao()->getDescricao(),
        ], 422);
    }
}

​
Auto-discovery

O SuotFiscalServiceProvider é registrado automaticamente pelo mecanismo de package auto-discovery do Laravel (presente desde o Laravel 5.5). Nenhuma alteração em config/app.php é necessária. Se o auto-discovery estiver desabilitado no seu projeto, registre o provider manualmente no array providers de bootstrap/providers.php (Laravel 11+) ou config/app.php (Laravel 10): 
// bootstrap/providers.php (Laravel 11+)
return [
    // ...
    \Suot\Fiscal\Laravel\SuotFiscalServiceProvider::class,
];

​
Próximos passos

Config Laravel

Referência completa de todas as opções do arquivo config/suot-fiscal.php.

Emitir CT-e

Construa e autorize seu primeiro CT-e com o SDK integrado ao Laravel.