# Como validar CPF na Shopify usando apps e APIs externas > Aprenda a integrar validação de CPF no checkout da Shopify usando apps nativos e APIs externas como a CPFHub.io para prevenir fraudes. **Publicado:** 14/04/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-validar-cpf-shopify-apps-apis-externas --- ## Introdução A Shopify é uma das plataformas de e-commerce mais populares no Brasil, usada por lojas de todos os portes -- desde empreendedores individuais até marcas consolidadas. No mercado brasileiro, a validação de CPF no checkout é um requisito quase obrigatório: além de ser necessária para a emissão de nota fiscal, ajuda a prevenir fraudes com cartões clonados e chargebacks. No entanto, a Shopify foi desenvolvida primariamente para o mercado norte-americano, e o campo de CPF não faz parte do checkout padrão. Para adicionar essa funcionalidade, lojistas brasileiros precisam recorrer a apps da Shopify App Store ou integrar APIs externas por meio de customizações. --- ## Por que validar CPF na Shopify ### Emissão de nota fiscal A legislação brasileira exige o CPF do comprador para emissão de NF-e e NFC-e. Sem o CPF validado, a loja não consegue emitir a nota fiscal corretamente, o que pode resultar em problemas fiscais. ### Prevenção de fraudes O Brasil tem uma das maiores taxas de fraude em e-commerce da América Latina. Validar o CPF do comprador e conferir se o nome corresponde ao titular do cartão é uma camada de segurança essencial contra chargebacks. ### Compliance regulatório Para lojas que vendem produtos regulados (medicamentos, bebidas alcoólicas, apostas, itens restritos por idade), a validação do CPF e da data de nascimento é obrigatória. ### Qualidade dos dados CPFs inválidos ou errados no banco de dados causam problemas em relatórios, integrações com ERPs e comunicações com clientes. Validar na entrada previne esses problemas. --- ## Abordagem 1: Apps da Shopify App Store A forma mais simples de adicionar validação de CPF é usando apps disponíveis na App Store da Shopify. ### Como funcionam Esses apps adicionam campos customizados ao checkout (CPF, CNPJ, inscrição estadual) e validam os dígitos verificadores. Alguns também integram com sistemas de emissão de nota fiscal. ### Limitações dos apps nativos * **Validação apenas matemática** -- A maioria dos apps verifica apenas os dígitos verificadores, sem consultar se o CPF realmente existe. * **Sem match de dados** -- Não conferem se o nome do comprador corresponde ao titular do CPF. * **Sem dados cadastrais** -- Não retornam nome, data de nascimento ou gênero do titular. * **Custo adicional** -- Apps de checkout customizado podem custar de US$ 10 a US$ 50/mês. --- ## Abordagem 2: Checkout Extensions com API externa Para validação completa, a melhor abordagem é usar as Checkout Extensions da Shopify combinadas com uma API externa de consulta de CPF. ### Como funciona 1. Uma Checkout UI Extension adiciona o campo de CPF ao checkout. 2. Quando o CPF é informado, uma Function Extension ou webhook envia o CPF para o seu backend. 3. O backend consulta a API da CPFHub.io para validar o CPF e obter os dados do titular. 4. Os dados retornados são usados para validação e auto-preenchimento. ### Backend para a integração ```javascript // server.js - Backend que recebe o CPF do checkout Shopify const express = require('express'); const app = express(); app.use(express.json()); app.post('/api/validar-cpf-checkout', async (req, res) => { const { cpf, nomeComprador } = req.body; const cpfLimpo = cpf.replace(/\D/g, ''); // Consultar CPFHub.io const response = await fetch( `https://api.cpfhub.io/cpf/${cpfLimpo}`, { method: 'GET', headers: { 'x-api-key': process.env.CPFHUB_API_KEY, 'Accept': 'application/json' } } ); if (!response.ok) { return res.json({ valido: false, motivo: 'CPF não encontrado ou inválido' }); } const dados = await response.json(); if (!dados.success) { return res.json({ valido: false, motivo: 'CPF não localizado na base' }); } // Match de nome const nomeTitular = dados.data.nameUpper; const nomeInformado = nomeComprador.toUpperCase().trim(); const primeiroNome = nomeInformado.split(' ')[0]; const nomeCorresponde = nomeTitular.includes(primeiroNome); return res.json({ valido: nomeCorresponde, titular: dados.data.name, motivo: nomeCorresponde ? 'CPF válido e nome corresponde' : 'Nome não corresponde ao titular do CPF' }); }); app.listen(3000); ``` ### Exemplo de consulta direta via cURL ```bash curl -X GET https://api.cpfhub.io/cpf/12345678900 \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Accept: application/json" ``` ```json { "success": true, "data": { "cpf": "12345678900", "name": "Juliana Costa Pereira", "nameUpper": "JULIANA COSTA PEREIRA", "gender": "F", "birthDate": "22/09/1991", "day": 22, "month": 9, "year": 1991 } } ``` --- ## Abordagem 3: Webhooks pós-pedido Para lojas que não querem modificar o checkout, uma abordagem alternativa é validar o CPF após o pedido ser criado, usando webhooks da Shopify. ### Como funciona 1. O checkout coleta o CPF em um campo customizado (metafield ou note attribute). 2. Quando o pedido é criado, a Shopify dispara um webhook `orders/create`. 3. O webhook é recebido pelo seu backend, que consulta a API da CPFHub.io. 4. Se o CPF for inválido ou o nome não corresponder, o pedido é sinalizado para revisão manual. ### Exemplo do webhook handler ```javascript app.post('/webhooks/shopify/orders-create', async (req, res) => { const pedido = req.body; const cpf = pedido.note_attributes?.find( attr => attr.name === 'cpf' )?.value; if (!cpf) { console.log('Pedido sem CPF:', pedido.id); return res.sendStatus(200); } const cpfLimpo = cpf.replace(/\D/g, ''); const response = await fetch( `https://api.cpfhub.io/cpf/${cpfLimpo}`, { headers: { 'x-api-key': process.env.CPFHUB_API_KEY, 'Accept': 'application/json' } } ); const dados = await response.json(); if (!dados.success) { await sinalizarPedidoParaRevisao(pedido.id, 'CPF inválido'); } else { const nomePedido = `${pedido.customer.first_name} ${pedido.customer.last_name}`.toUpperCase(); const nomeTitular = dados.data.nameUpper; if (!nomeTitular.includes(nomePedido.split(' ')[0])) { await sinalizarPedidoParaRevisao( pedido.id, 'Nome não corresponde ao CPF' ); } } res.sendStatus(200); }); ``` --- ## Comparativo das abordagens | Critério | App nativo | Checkout Extension + API | Webhook pós-pedido | | --- | --- | --- | --- | | Complexidade de implementação | Baixa | Média | Média | | Validação em tempo real | Apenas dígitos | Completa (API) | Não (pós-pedido) | | Match de nome | Não | Sim | Sim | | Impacto no checkout | Mínimo | Moderado | Nenhum | | Prevenção de fraude | Limitada | Alta | Moderada (após a compra) | | Custo | US$ 10-50/mês (app) | R$ 0-149/mês (API) | R$ 0-149/mês (API) | --- ## Configurando a CPFHub.io para sua loja Shopify ### Passo 1: Criar conta Acesse [cpfhub.io](https://www.cpfhub.io/) e crie uma conta gratuita — sem cartão de crédito, com 50 consultas mensais incluídas. ### Passo 2: Gerar chave de API No painel de controle (app.cpfhub.io), gere sua chave de API. ### Passo 3: Implementar o backend Crie um servidor simples (Node.js, Python, PHP) que receba o CPF do checkout e consulte a API da CPFHub.io. Hospede em um serviço como Vercel, Railway ou Heroku. ### Passo 4: Integrar com o checkout Conecte o backend ao checkout da Shopify via Checkout Extension, app customizado ou webhook. ### Passo 5: Monitorar Acompanhe o volume de consultas no dashboard da CPFHub.io e faça upgrade para o Plano Pro quando necessário. --- ## Quando fazer upgrade do plano | Volume mensal de pedidos | Plano recomendado | Custo | | --- | --- | --- | | Até 50 | Gratuito | R$ 0 | | 50 a 1.000 | Pro | R$ 149/mês | | Acima de 1.000 | Corporativo | Sob consulta | --- ## Perguntas frequentes ### O que é necessário para implementar validação de CPF neste contexto? A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação. ### A API CPFHub.io funciona para todos os volumes de consulta? Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional. ### Como garantir conformidade com a LGPD ao usar uma API de CPF? Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A [ANPD](https://www.gov.br/anpd) orienta que dados de identificação devem ser tratados com o princípio da necessidade. ### Quanto tempo leva para integrar a API CPFHub.io? A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens. ### Leia também - [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest) - [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf) --- ## Conclusão Validar CPF na Shopify é essencial para emissão de nota fiscal, prevenção de fraudes e qualidade dos dados. Enquanto apps nativos oferecem apenas validação matemática dos dígitos, a integração com a [**CPFHub.io**](https://www.cpfhub.io/) entrega validação completa com match de nome — a diferença entre bloquear uma fraude e deixá-la passar. Com plano gratuito de 50 consultas mensais e documentação em mais de 13 linguagens, a CPFHub.io é acessível para lojas de todos os portes. Crie sua conta em [cpfhub.io](https://www.cpfhub.io/).