Como implementei o agendador de verificação de pré-postagens dos Correios no Laravel · FelipeParaiz0

Contexto

Durante o desenvolvimento do sistema de pré-postagens, surgiu a necessidade de verificar periodicamente o status das encomendas enviadas para os Correios. A ideia era automatizar essa verificação, evitando que os usuários precisassem consultar manualmente dando reload na página para saber se uma pré-postagem havia sido postada ou ainda estava pendente.

Inicialmente, a aplicação não possuía nenhum tipo de agendamento de tarefas, então a primeira etapa foi configurar um agendador (scheduler) no Laravel para executar automaticamente essa verificação em intervalos regulares.

O problema

O desafio principal era garantir que o comando personalizado fosse executado corretamente no ambiente de desenvolvimento e produção, respeitando a estrutura do Laravel 12.

Durante a implementação, enfrentei alguns problemas:

O Kernel não estava carregando o comando no ambiente local.
As rotas do console não estavam sendo interpretadas corretamente quando o scheduler tentava executar.

Esses erros ocorriam porque o comando ainda não estava registrado no arquivo de rotas do console (routes/console.php) e, portanto, o Laravel não sabia como agendar a execução.

A solução

1. Criação do comando Artisan

Primeiro, criei um novo comando Artisan para consultar a API dos Correios:

php artisan make:command CheckCorreiosPrepostagens

Esse comando foi registrado em app/Console/Commands/CheckCorreiosPrepostagens.php.
Dentro dele, implementei a lógica para buscar as pré-postagens no banco e consultar a API dos Correios:

public function handle()
{
    $this->info('Iniciando verificação de pré-postagens dos Correios...');
    // Lógica para consultar a API dos Correios e atualizar o status
    $this->info('Verificação de pré-postagens concluída.');
}

2. Registro do comando no scheduler

No arquivo routes/console.php, adicionei a configuração do agendamento:

use Illuminate\Support\Facades\Schedule;

Schedule::command('correios:check-prepostagens')
  ->everyFiveMinutes()
  ->withoutOverlapping();

Isso garante que o Laravel execute o comando automaticamente a cada 5 minutos.

3. Teste do agendador

Para testar localmente, utilizei o comando:

php artisan schedule:work

Esse comando mantém o scheduler rodando em tempo real no terminal e executa as tarefas conforme o cron configurado.

O commit final

Depois de ajustar tudo, criei um commit descritivo seguindo o padrão Conventional Commits:

Commit em PT-BR

git commit -m "feat: Implementa agendador para verificação de pré-postagens Correios" \
-m "Adiciona o comando Artisan `correios:check-prepostagens` para consultar a API dos Correios e verificar o status de postagem. O comando foi agendado para rodar a cada 5 minutos, utilizando o `routes/console.php` para garantir o carregamento correto no ambiente de desenvolvimento."

Commit em EN

git commit -m 'feat: Implements scheduler for checking Correios pre-posts' 
-m 'Adds the Artisan command \`correios:check-prepostagens\` to query the Correios API and check the posting status. The command is scheduled to run every 5 minutes, using `routes/console.php` to ensure correct loading in the development environment."

Esse commit contém um título curto e objetivo e uma descrição explicando a motivação e a implementação técnica.

Conclusão

Com essa implementação, o sistema agora realiza automaticamente a verificação das pré-postagens, garantindo que os status estejam sempre atualizados sem depender de ações manuais.

Além de simplificar o processo, essa automação melhora a confiabilidade das informações e reduz o risco de falhas humanas. O uso do routes/console.php também torna o ambiente de desenvolvimento mais consistente com a produção, garantindo que o agendador funcione corretamente em ambos.

Resumo técnico:

Laravel 12
Comando Artisan: correios:check-prepostagens
Scheduler configurado com Schedule::command()
Execução automática a cada 5 minutos
Commit documentado com mensagem e descrição detalhada

Link para o commit