Rejeições de CT-e - SUOT Developers

O quê / quando

A SEFAZ (ou validação fiscal) recusou a operação. O Handler devolve Result rejeitado com código e mensagem. Use a orientação acionável antes de reenviar.

Ler a rejeição

use Suot\Fiscal\Core\Exception\InfrastructureException;
use Suot\Fiscal\Core\Result\RetryMode;

try {
    $result = $cte->issue()
        ->forOperation('ot-123')
        ->inHomologation()
        // … cadeia …
        ->handle();
} catch (InfrastructureException $e) {
    $failure = $e->toFailure('issue');
    // Host: alertar; não tratar como rejeição fiscal
    throw $e;
}

if ($result->isRejected()) {
    $failure = $result->failure();
    // $failure->code, $failure->message
    // $failure->recoveryGuide->summary
    // steps com relatedField (caminho público, ex.: shipper.stateRegistration)

    $policy = $result->retryPolicy();
    match ($policy?->mode) {
        RetryMode::AfterCorrection => /* corrigir e remontar emissão */,
        RetryMode::QueryBeforeRetry => /* byAccessKey() antes de reemitir */,
        RetryMode::AfterDelay, RetryMode::Immediate => /* filar conforme política */,
        RetryMode::Never, null => /* definitivo; não reenviar */,
    };
}

Corrigir e reemitir

Com AfterCorrection, remonte a cadeia com dados corrigidos e novo forOperation:

use Suot\Fiscal\Core\Exception\InfrastructureException;
use Suot\Fiscal\Core\Result\RetryMode;
use Suot\Fiscal\Cte\Data\CteParty;

try {
    $result = $cte->issue()
        ->forOperation('ot-123-retry') // novo operationId
        ->inHomologation()
        // … mesma cadeia, com forShipper($shipperCorrigido) …
        ->forShipper($shipperCorrigido)
        ->handle();
} catch (InfrastructureException $e) {
    $failure = $e->toFailure('issue');
    // Host: alertar; filar conforme $failure->retryPolicy
    throw $e;
}

if ($result->isAuthorized()) {
    // Host: persistir artefatos da nova autorização
}

if ($result->isRejected()) {
    $failure = $result->failure();
    $policy = $result->retryPolicy();
    // Host: repetir o match de RetryMode; Never → não reenviar
}

Não reutilize o XML assinado anterior após alterar dados fiscais. Gere novo documento com novo operationId.

Se você já materializou um IssueCteCommand (por exemplo via Handlers no Laravel Bridge), revise() reconstrói a intenção sem mutar o command original — útil com withOperationId() e campos corrigidos. Na API padrão, prefira remontar $cte->issue()….

Não confundir

Rejeição fiscal	Infraestrutura
Result + `failure()`	`InfrastructureException`
Corrigir / consultar / aguardar	Retry de rede, cert, timeout com política do host

Detalhes de modos: Retry.