Skip to main content
O SUOT ANTT SDK separa explicitamente dois tipos de problemas: rejeições esperadas, que são respostas regulatórias da ANTT a dados incorretos ou situações de negócio inválidas, e falhas técnicas, que são impedimentos de infraestrutura que não chegam à ANTT. Entender essa distinção é essencial para construir um tratamento de erros correto e evitar loops de retry desnecessários.

​
Rejeições esperadas

Rejeições esperadas ocorrem quando a ANTT processou a requisição e retornou uma negativa com fundamento regulatório. Elas são retornadas dentro do Result — não há exceção lançada. Exemplos comuns de rejeição:
Código (exemplo)Situação
CIOT_DUPLICADOO CIOT já foi registrado para esta operação
RNTRC_INATIVOO transportador consultado está com RNTRC inativo ou suspenso
RNTRC_NAO_ENCONTRADONenhum registro RNTRC encontrado para o CNPJ/CPF informado
CNPJ_INVALIDOO CNPJ informado não é válido segundo as regras da ANTT
OPERACAO_NAO_PERMITIDAA operação não é permitida para a categoria do transportador
DADOS_INCONSISTENTESOs dados da operação apresentam inconsistência regulatória
<?php

$result = $handler->registrar(command: $command);

if (! $result->isSuccess()) {
    $rejeicao = $result->getRejection();

    // Registre a rejeição com contexto suficiente para diagnóstico
    logger()->warning('Rejeição ANTT', [
        'operacao'  => 'registrar-ciot',
        'codigo'    => $rejeicao->codigo,
        'mensagem'  => $rejeicao->mensagem,
        'detalhes'  => $rejeicao->detalhes ?? null,
    ]);

    // Decida o fluxo com base no código da rejeição
    match ($rejeicao->codigo) {
        'CIOT_DUPLICADO'      => throw new CiotDuplicadoException($rejeicao->mensagem),
        'RNTRC_INATIVO'       => throw new TransportadorInativoException($rejeicao->mensagem),
        default               => throw new RejeicaoAnttException($rejeicao->codigo, $rejeicao->mensagem),
    };
}

​
Falhas técnicas

Falhas técnicas ocorrem quando algo impediu que a operação chegasse à ANTT ou que a resposta fosse processada. O SDK lança InfrastructureException — nunca retorna um Result com falha técnica. Causas comuns:
CausaDescrição
ConectividadeSem acesso à rede ou ao endpoint da ANTT
TimeoutA ANTT não respondeu dentro do prazo configurado
AutenticaçãoCredenciais inválidas, expiradas ou sem permissão
Resposta malformadaA ANTT retornou uma resposta fora do formato esperado
<?php

use Suot\Antt\Core\Exception\InfrastructureException;

try {
    $result = $handler->registrar(command: $command);

    // Trate sucesso e rejeição esperada aqui
} catch (InfrastructureException $e) {
    logger()->error('Falha técnica ANTT SDK', [
        'operacao'  => 'registrar-ciot',
        'mensagem'  => $e->getMessage(),
        'codigo'    => $e->getCode(),
        'trace'     => $e->getTraceAsString(),
    ]);

    // Notifique o time de operações
    // Aplique retry com backoff exponencial conforme a política definida
    // NÃO reprocesse imediatamente
}

​
Padrão completo de tratamento

<?php

use Suot\Antt\Core\Exception\InfrastructureException;

try {
    $result = $handler->registrar(command: $command);

    if ($result->isSuccess()) {
        $dados = $result->getData();

        // Operação concluída com sucesso
        echo 'CIOT: ' . $dados->numeroCiot . PHP_EOL;

    } else {
        // Rejeição esperada: corrija os dados e reconstrua o Command
        $rejeicao = $result->getRejection();

        echo 'Rejeição [' . $rejeicao->codigo . ']: ' . $rejeicao->mensagem . PHP_EOL;
    }

} catch (InfrastructureException $e) {
    // Falha técnica: aplique retry com backoff ou escale para o time de operações
    echo 'Falha técnica: ' . $e->getMessage() . PHP_EOL;
}

​
Quando reconstruir o Command

Reconstrua o Command quando $result->isSuccess() retornar false. A rejeição indica que os dados enviados não satisfazem as regras regulatórias da ANTT. O fluxo correto é:
  1. Ler o codigo e a mensagem da rejeição
  2. Identificar qual campo ou regra causou a rejeição
  3. Corrigir os dados na camada de negócio da sua aplicação
  4. Construir um novo Command com os dados corrigidos
  5. Executar novamente
Não faça retry de rejeições esperadas. Reenviar o mesmo Command sem corrigir os dados apenas duplicará a rejeição. Rejeições esperadas não são erros transitórios — são respostas definitivas da ANTT com base nos dados que você enviou.

​
Retry para falhas técnicas

Falhas técnicas (InfrastructureException) podem ser transitórias — uma queda momentânea de conectividade ou um timeout eventual. Nesses casos, retry com backoff exponencial é apropriado. Os mesmos conceitos de RetryPolicy utilizados no SUOT Fiscal SDK se aplicam aqui. Consulte o guia de RetryPolicy para implementação detalhada de políticas de retry, incluindo jitter, número máximo de tentativas e circuito aberto.