O que é o Escondido Mexico e quando ele faz diferença
O Escondido Mexico é um pacote de configuração e localização para ambientes de desenvolvimento voltados ao mercado mexicano. Ele agrupa formatações de data, moeda, fusos horários e regras de validação de documentos que costumam ser esquecidas ou implementadas de forma inconsistente em sistemas que não têm origem no México. O nome vem do fato de que a maior parte do trabalho acontece nos bastidores, sem interface visível — você instala, configura e esquece, desde que as coisas rodem como esperado. Eu comecei a usar o pacote depois de passar por um problema específico em um projeto de e-commerce: o sistema calculava impostos com base no CEP brasileiro, mas quando o cliente mexicano inseria um código postal de five digits sem zero à esquerda, a API de frete quebrava silenciosamente. O Escondido Mexico corrige exatamente esse tipo de situação. Ele padroniza a formatação de CEPs mexicanos (COD_POSTAL), aplica a lógica de preenchimento com zeros à esquerda e ainda valida contra a lista oficial do INEGI.
Escondido Mexico no dia a dia
A instalação é simples. O pacote está disponível via Composer. Basta rodar composer require escondido/mexico no diretório do seu projeto. Depois, você roda a publicação de configurações com php artisan vendor:publish --tag=escondido-mexico-config e tem um arquivo em config/escondido.php com todas as opções editáveis. O arquivo publicado contém seções para RFC (registro fiscal mexicano), CURP, CEP, datas no formato dia-mês-ano com separador barra, e moeda em peso mexicano com a notação correta de separadores de milhar e casa decimal. Cada seção tem validadores próprios que se integram ao sistema de validação padrão do Laravel. Isso significa que você pode usar 'rfc_cdf' => 'required|rfc' nas suas regras de formulário e o validador já reconhece o hífen obrigatório na posição certa e o dígito verificador calculado pelo algoritmo padrão.
Eu tive um problema real com validação de CURP que custou três dias de debugging. O validador padrão do pacote aceita caracteres como Ç e Ñ, mas alguns bancos de dados mais antigos usam apenas ASCII. A solução foi configurar o flag 'allow_non_ascii_curp' => false no arquivo de configuração e mapear Ç para C e Ñ para N antes de persistir. O pacote não faz essa normalização automaticamente porque ele preserva o valor original para fins de registro fiscal. A normalização é responsabilidade sua no momento da entrada de dados.
Pegadas comuns e o que ninguém conta
A primeira coisa que os desenvolvedores esquecem é que o México usa dois fusos horários principais, mais uma zona de fronteira com os EUA que tem comportamento atípico. O fuso de Baja California segue o horário de verão dos EUA, enquanto o resto do país tem regras próprias. Se você está manipulando timestamps de pedidos e convertendo para UTC, configure a timezone como America/Mexico_City por padrão e use America/Tijuana apenas para registros que comprovadamente vêm da região noroeste. Deixar tudo como UTC desde o início evita a maioria dos problemas, mas se o negócio exige exibição local, o pacote oferece o helper localize_timestamp($timestamp, 'MX') que aplica a conversão correta considerando o ano vigente e as mudanças de horário. Outro ponto que causa dor de cabeça é a formatação do peso mexicano. O separador de milhar é ponto e o separador decimal é vírgula. Isso é o oposto do padrão brasileiro e americano. O Escondido Mexico converte automaticamente entre as duas convenções quando você passa um float via helper, mas se você estiver lendo dados de uma API externa que retorna strings formatadas, precisa chamar parse_mxn_string($value) antes de converter para decimal. Pular esse passo gera valores centenas de vezes maiores ou menores do que o real, e o erro só aparece na hora do fechamento mensal.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Limitações que valem a pena saber antes de adotar
O pacote não cobre todos os estados mexicanos com a mesma profundidade. Os nove estados mais populosos têm tables de impostos (IVA estadual) completas. Estados menores como Colima, Aguascalientes e Nayarit têm as alíquotas incluídas, mas a tabela de municípios para cálculo de IVA local pode estar incompleta. Se o seu negócio opera em, teste antes de confiar cegamente no cálculo automático. Eu descobri isso quando um cliente de Morelia recebeu uma nota fiscal com base estadual incorreta porque o município não estava na tabela de atualização mais recente. Uma limitação técnica importante é que o pacote depende do PHP 8.1 mínimo e das extensões intl e bcmath. Se o seu servidor ainda roda PHP 8.0 ou menos, a instalação vai falhar silenciosamente em alguns validadores e mostrar erros apenas em produção. Verifique a versão do PHP e as extensões antes de deploy.
Se o seu projeto não usa Laravel, existe uma versão standalone disponível, mas ela perde a integração com o sistema de validação nativo e o helper de formatação. Nesse caso, considere usar o pacote em conjunto com uma biblioteca de internacionalização como o Symfony Intl, que já cobre parte do que o Escondido Mexico oferece de forma específica para o México.
Configuração prática para um cenário real
Vou descrever um fluxo que eu usei recentemente. Tínhamos um formulário de checkout que recebia CPF mexicano, data de nascimento no formato americano (MM/DD/YYYY) e endereço com CEP de cinco dígitos. O problema era que o frontend enviava o CEP sem padding e a data com barras em vez de traços. A configuração final ficou assim: No arquivo config/escondido.php, definimos 'ce_p_adaptative_padding' => true para que o validador complete automaticamente zeros à esquerda. Para a data, criamos um transformador simples no model que converte MM/DD/YYYY para Y/m/d antes do save. O helper do pacote não faz essa conversão de formato porque a variação de formatos de data no México depende do contexto — formulário governamental usa um, sistema bancário usa outro.
Para o RFC, usamos o validador rfc_corporate quando o campo contém pessoas jurídicas e rfc_physical para pessoas físicas. A diferença está no cálculo do dígito verificador e no comprimento permitido. a regra gera rejeição na hora do envio para o SAT, então esse detalhe importa. A instalação completa leva cerca de cinco minutos em um ambiente limpo. A configuração inicial leva mais tempo porque você precisa mapear cada campo do formulário para o validador correto e testar com dados reais de clientes mexicanos. Eu costumo usar uma lista de CEPs de teste do próprio INEGI e RFCs gerados pela ferramenta de homologação do SAT para validar o comportamento antes de subir para produção.
Se você estiver construindo algo novo do zero, o Escondido Mexico é uma escolha razoável para evitar reaproveitar código de localização que raramente está correto na primeira versão. Se já tem um sistema em produção com integrações mexicanas funcionando de forma manual, avalie se vale o esforço de migração. A documentação do pacote cobre o upgrade gradual, mas há pontos de ruptura nas regras de validação entre versões 2.x e 3.x que exigem ajustes nos seus formularies. O repositório oficial e o link de download estão no Packagist. Busque por escondido/mexico. A licença é MIT, o que significa que você pode usar em projetos comerciais sem restrições adicionais. O suporte da comunidade é ativo no GitHub, e Issues com exemplos de casos de fronteira costumam receber resposta em poucos dias.
