Como validar CPF na Shopify usando apps e 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

// 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

curl -X GET https://api.cpfhub.io/cpf/12345678900 \
    -H "x-api-key: SUA_CHAVE_DE_API" \
    -H "Accept: application/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

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

Configurando a CPFHub.io para sua loja Shopify

Passo 1: Criar conta

Acesse 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

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 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.

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 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.