> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suot.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart SUOT Fiscal SDK: emitindo o primeiro CT-e

> Instale o SUOT Fiscal SDK, configure o Composer com o registry privado e autorize seu primeiro CT-e de teste em menos de 15 minutos.

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.

<Info>
  **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](https://developers.suot.dev) com uma organização ativa
  * Token Composer gerado para o seu usuário (você vai gerar um no Passo 2)
</Info>

<Steps>
  <Step title="Acesse o Developer Portal e crie uma organização">
    Acesse [developers.suot.dev](https://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.

    <Note>
      Veja o guia completo em [Organizações](/platform/organizacoes) para entender papéis, membros e associação de licenças.
    </Note>
  </Step>

  <Step title="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.

    <Warning>
      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.
    </Warning>

    Para gerenciar tokens depois, acesse [platform/tokens-composer](/platform/tokens-composer).
  </Step>

  <Step title="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.

    ```json composer.json theme={null}
    {
      "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`.**

    ```bash theme={null}
    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.

    <Note>
      Se preferir usar `auth.json` localmente, certifique-se de adicioná-lo ao `.gitignore`. Veja detalhes em [Tokens Composer](/platform/tokens-composer).
    </Note>
  </Step>

  <Step title="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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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 theme={null}
    <?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();
    ```

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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 theme={null}
    <?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);
    ```
  </Step>

  <Step title="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 theme={null}
    <?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();
    }
    ```

    <Note>
      Em ambiente de homologação, a SEFAZ pode retornar rejeições específicas para dados de teste. Consulte o [Guia de Homologação](/guias/homologacao) para configurar cenários de teste corretamente.
    </Note>
  </Step>
</Steps>

<Tip>
  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](/guias/homologacao).
</Tip>

<Note>
  Para gerenciar, renovar ou revogar tokens Composer — incluindo tokens de CI/CD —, acesse [Tokens Composer](/platform/tokens-composer).
</Note>