Envio aéreo recusado por falta de um campo
Todo envio de loja com CNPJ por uma transportadora aérea era recusado pela API, porque a plataforma não tinha onde cadastrar o CNAE. Delimitei o escopo com testes reais e criei o campo de forma que ele só entra no envio quando existe, sem mudar nada para quem não usa.
- Papel
- Desenvolvedor responsável, do diagnóstico à entrega
- Contexto
- Plataforma de e-commerce multi-tenant
- Stack
- PHP, Symfony, Doctrine, MySQL, PHPUnit
- Time
- Solo
- Período
- 2026
Case anonimizado: nomes de empresa, cliente e pessoas foram omitidos ou trocados.
01. Situação
Todo envio aéreo de loja com CNPJ era recusado
As lojas da plataforma contratam fretes por um agregador que reúne várias transportadoras. Quando o cliente escolhia uma transportadora aérea de cargas, o pedido não entrava no carrinho do agregador e a etiqueta não era gerada. A API respondia com erro 422 dizendo que o CNAE era obrigatório para envios com CNPJ.
Analisei o erro em produção e abri o chamado com o diagnóstico. Como o remetente é sempre a loja, e a loja tem CNPJ, não era um caso isolado: todo envio por essa transportadora falhava. O pedido ainda mostrava o texto cru da API, sem dizer ao lojista onde resolver.
02. Investigação
Faltava um campo que a plataforma não tinha onde guardar
Li a documentação do agregador e comparei com o payload que a plataforma enviava. Para pessoa jurídica, o CNPJ é obrigatório e a inscrição estadual e o CNAE devem ser enviados "se houver", sendo o CNAE obrigatório para essa transportadora. A plataforma já enviava CPF, CNPJ e IE, mas não tinha campo para o CNAE, nem da loja nem do cliente.
Sobrava uma dúvida que definia o tamanho do trabalho: o CNAE também seria exigido do cliente pessoa jurídica? Se fosse, a mudança chegaria ao cadastro de clientes. A documentação não respondia, então testei com envios reais numa conta de testes: um envio de PJ para PJ passou com o CNAE só do remetente. Com essa evidência, mantive o escopo na configuração da integração.
03. Solução
Um campo opcional que só aparece no payload quando existe
Criei na configuração da integração um campo opcional de CNAE, guardado só com os 7 dígitos. Quando ele está preenchido e a loja tem CNPJ, vai no remetente do envio. Sem ele, a chave nem aparece no JSON, e o payload fica idêntico ao anterior. Tratei isso como requisito: nenhuma loja que já funcionava poderia perceber a mudança. Também reescrevi a mensagem do erro, que passou a dizer onde cadastrar o CNAE.
Escolha
Enviar para todas as transportadoras
Avaliei filtrar por id de serviço, por nome ou por nova tentativa após o erro. Descartei: a documentação manda enviar o CNAE de PJ quando houver, as outras transportadoras que testei aceitaram o campo, e um filtro quebraria se a transportadora mudasse de serviço.
Escolha
Guardar na configuração da integração
Só esta integração usa o dado. Mexer no cadastro do CNPJ da loja afetaria vários fluxos sem necessidade.
Cuidado
Fora do salvamento automático
Percebi que a tela salva as credenciais por um caminho que desconecta a conta. Fiz o campo novo ser salvo pelo formulário, sem derrubar a integração.
Escrevi 10 testes novos, incluindo um que compara as chaves do remetente com as de antes, para provar que nada muda sem o CNAE. A migração foi executada em um schema temporário nos três cenários: criar, repetir sem efeito e desfazer.
04. Resultado
O envio passa, e quem não usa o campo não percebe mudança
- transportadoras validadas com envios reais
- 5
- testes novos
- 10
Com o CNAE cadastrado, o envio aéreo é aceito, e as outras quatro transportadoras que validei recebem o campo normalmente. Lojas sem CNAE continuam enviando exatamente o mesmo payload. Os pedidos que tinham falhado podem ser reenviados pelo botão que já existia na tela de volumes.