CPF no checkout do Magento 2 usando o campo Tax/VAT que já existe

São dois campos, não um

Guarde essa tabela, ela resolve 90% das dúvidas:

O taxvat pendura no cliente, então ele é um só, independente de quantos endereços a pessoa tenha. O vat_id pendura no endereço, então cada endereço tem o seu — o que faz sentido pra quem compra com CNPJ da empresa e CPF de casa.

O detalhe que pega: o formulário de endereço do checkout é montado a partir dos atributos do customer_address, e o taxvat não é um deles. Por isso ligar só o Tax/VAT Number no admin e ir olhar o checkout não mostra nada.

Ligando cada um

Pelo admin, os caminhos são:

• Stores > Configuration > Customers > Customer Configuration > Name and Address Options > Show Tax/VAT Number, com as opções No, Optional e Required.
• Stores > Configuration > Customers > Customer Configuration > Create New Account Options > Show VAT Number on Storefront, Yes ou No.

Pela CLI, que é o que eu uso em deploy:

php bin/magento config:set customer/address/taxvat_show req
php bin/magento config:set customer/create_account/vat_frontend_visibility 1
php bin/magento cache:flush

Uma coisa que ninguém conta sobre o primeiro comando: ele não guarda só um valor de configuração. O backend model Magento\Customer\Model\Config\Backend\Show\Customer escreve is_visible e is_required direto no atributo EAV taxvat. É por isso que req torna o campo obrigatório também no cadastro pelo admin, e é por isso que a mudança não volta sozinha se você só limpar o cache.

Já o vat_frontend_visibility só liga a visibilidade. Quem decide isso é uma linha do AttributeMerger do checkout, que esconde o vat_id quando a config está desligada. Deixar o campo obrigatório no checkout exige mexer no is_required do atributo, o que já é data patch ou SQL — aí não é mais "sem módulo".

Troque o rótulo para CPF / CNPJ

"VAT Number" não diz nada pro brasileiro. O rótulo do campo no checkout passa por __() antes de ir pra tela, então uma linha de tradução resolve, sem tocar em código. Crie o arquivo app/design/frontend/SuaMarca/seu-tema/i18n/pt_BR.csv com:

"VAT Number","CPF / CNPJ"
"Tax/VAT Number","CPF / CNPJ"

Depois:

php bin/magento setup:static-content:deploy pt_BR -f
php bin/magento cache:clean translate full_page

Se a loja usa mais de um idioma, repita no CSV do idioma que interessa. E confira que a store view está mesmo em pt_BR em Stores > Configuration > General > Locale Options, senão o CSV nem é lido.

O que isso não faz

Não valida CPF. O campo aceita "123" e salva feliz. O Magento tem validação de VAT europeu via VIES, que não serve pra nada aqui. Se você precisa de máscara e de dígito verificador, aí sim entra módulo ou um validador seu.

O que vale checar antes de comprar qualquer coisa: o seu gateway provavelmente já lê desses campos. O módulo do PagBank, por exemplo, tem uma configuração chamada Get Document From, em payment/ricardomartins_pagbank/document_from, com exatamente três opções — taxvat, vat_id ou pedir no próprio formulário de pagamento.

Pra loja que vende muito pra convidado, a terceira opção costuma ser a mais tranquila: o gateway pede o documento na hora de pagar, com máscara e validação prontas, e você não precisa nem ligar os campos do core. Ligue o taxvat como req quando o cadastro for obrigatório de qualquer jeito e você quiser o documento no cliente, não no pedido.