Como integrar API de CPF em ERPs open source (Odoo, ERPNext)

A API da CPFHub.io pode ser integrada a ERPs open source como Odoo e ERPNext adicionando um método de validação ao model de parceiro (Odoo) ou um Server Script no evento before_save do documento Customer (ERPNext). Em ambos os casos, uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key retorna o nome e os dados cadastrais do titular, permitindo validar CPFs automaticamente no momento do cadastro e evitar rejeições de NF-e junto à SEFAZ.

Introdução

Sistemas ERP (Enterprise Resource Planning) são o coração operacional de muitas empresas brasileiras. Eles centralizam informações de clientes, fornecedores, colaboradores e transações financeiras. Garantir que os CPFs registrados nesses sistemas sejam válidos é fundamental para evitar erros em notas fiscais, duplicidades cadastrais e problemas com a Receita Federal.

ERPs open source como Odoo e ERPNext são amplamente adotados por empresas de todos os portes devido à flexibilidade e ao custo reduzido.

Por que validar CPF no ERP

A validação de CPF diretamente no ERP traz benefícios operacionais significativos:

• Prevenção de erros fiscais -- Um CPF inválido pode causar a rejeição de notas fiscais eletrônicas (NF-e), gerando retrabalho e atrasos.

• Cadastros limpos -- Evitar duplicidades e registros com dados incorretos mantém a base de dados do ERP confiável.

• Automação -- Eliminar a necessidade de conferência manual de CPFs reduz o tempo gasto pela equipe administrativa.

• Conformidade -- Manter CPFs validados facilita auditorias e garante conformidade com obrigações acessórias.

Visão geral da API da CPFHub.io

A API utiliza uma requisição GET simples, com autenticação por chave de API no header:

curl -X GET https://api.cpfhub.io/cpf/12345678900 \
    -H "x-api-key: SUA_CHAVE_DE_API" \
    -H "Accept: application/json" \
    --max-time 10

Resposta:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

Integração com Odoo

O Odoo é um ERP open source escrito em Python que utiliza um sistema de módulos para estender suas funcionalidades. A integração com a API de CPF pode ser feita criando um módulo customizado ou adicionando lógica a um módulo existente.

Criando um método de validação no modelo de parceiro

No Odoo, clientes e fornecedores são representados pelo modelo res.partner. Abaixo está um exemplo de como adicionar um método de validação de CPF que consulta a API da CPFHub.io.

import requests
import logging
from odoo import models, fields, api
from odoo.exceptions import ValidationError

_logger = logging.getLogger(__name__)

class ResPartner(models.Model):
    _inherit = 'res.partner'

    cpf_validado = fields.Boolean(string='CPF Validado', default=False)
    cpf_nome_receita = fields.Char(string='Nome na Receita')

    def action_validar_cpf(self):
    self.ensure_one()
    if not self.vat:
    raise ValidationError("CPF não informado.")

    cpf = self.vat.replace('.', '').replace('-', '').replace('/', '')
    url = f"https://api.cpfhub.io/cpf/{cpf}"
    headers = {
    "x-api-key": self.env['ir.config_parameter'].sudo().get_param(
    'cpfhub.api_key', default=''
    ),
    "Accept": "application/json"
    }

    try:
    response = requests.get(url, headers=headers, timeout=10)
    if response.status_code == 200:
    dados = response.json()
    if dados.get("success"):
    self.write({
    'cpf_validado': True,
    'cpf_nome_receita': dados['data']['name']
    })
    _logger.info(f"CPF {cpf} validado com sucesso.")
    else:
    self.write({'cpf_validado': False})
    raise ValidationError("CPF não encontrado na base de dados.")
    else:
    raise ValidationError(
    f"Erro na consulta: código {response.status_code}"
    )
    except requests.exceptions.Timeout:
    raise ValidationError("A consulta excedeu o tempo limite.")
    except requests.exceptions.RequestException as e:
    _logger.error(f"Erro ao consultar CPF: {e}")
    raise ValidationError("Erro de conexão ao validar CPF.")

Configurando a chave de API no Odoo

A chave de API deve ser armazenada como parâmetro do sistema, acessível em Configurações > Técnico > Parâmetros do sistema:

• Chave -- cpfhub.api_key
• Valor -- Sua chave de API da CPFHub.io

Essa abordagem evita que a chave fique exposta no código-fonte.

Integração com ERPNext

O ERPNext é um ERP open source construído sobre o framework Frappe, também escrito em Python. A integração segue uma lógica semelhante, utilizando hooks e scripts do Frappe.

Criando um Server Script no ERPNext

No ERPNext, é possível criar Server Scripts que são executados em eventos específicos, como a criação ou atualização de um documento. Abaixo está um exemplo de script que válida o CPF ao salvar um registro de cliente (Customer).

import requests
import frappe

def validar_cpf_cliente(doc, method):
    if not doc.tax_id:
    return

    cpf = doc.tax_id.replace('.', '').replace('-', '').replace('/', '')

    if len(cpf) != 11:
    return

    api_key = frappe.get_single_value('CPFHub Settings', 'api_key')
    if not api_key:
    frappe.log_error("Chave de API da CPFHub não configurada.")
    return

    url = f"https://api.cpfhub.io/cpf/{cpf}"
    headers = {
    "x-api-key": api_key,
    "Accept": "application/json"
    }

    try:
    response = requests.get(url, headers=headers, timeout=10)
    if response.status_code == 200:
    dados = response.json()
    if dados.get("success"):
    doc.db_set('custom_cpf_validado', 1)
    doc.db_set('custom_nome_receita', dados['data']['name'])
    frappe.msgprint(
    f"CPF validado. Nome: {dados['data']['name']}",
    title="Validação de CPF"
    )
    else:
    doc.db_set('custom_cpf_validado', 0)
    frappe.msgprint(
    "CPF não encontrado na base de dados.",
    title="Validação de CPF",
    indicator="red"
    )
    except requests.exceptions.Timeout:
    frappe.log_error("Timeout ao consultar CPF via CPFHub.")
    except requests.exceptions.RequestException as e:
    frappe.log_error(f"Erro ao consultar CPF: {e}")

Registrando o hook

No arquivo hooks.py do aplicativo customizado:

doc_events = {
    "Customer": {
    "before_save": "meu_app.utils.validar_cpf_cliente"
    }
}

Cenários de uso em ERPs

Cadastro de clientes

Ao registrar um novo cliente no ERP, o CPF é validado automaticamente. Se o CPF for inválido, o sistema alerta o operador antes de salvar o registro.

Emissão de notas fiscais

Antes de gerar uma NF-e, o sistema verifica se o CPF do destinatário é válido. Isso evita rejeições por parte da SEFAZ.

Onboarding de fornecedores

Fornecedores pessoa física também precisam ter seus CPFs validados para garantir a correta emissão de pagamentos e retenções fiscais.

Atualização cadastral em massa

Utilizando scripts batch com respeito ao rate limit da API, é possível validar toda a base de clientes existente e marcar registros com dados inconsistentes para revisão.

Planos recomendados para ERPs

Boas práticas de integração

• Timeout -- Sempre configure timeout nas requisições para evitar que o ERP fique travado aguardando resposta.

• Tratamento de erros -- Implemente tratamento para os códigos HTTP 400, 401 e 500 retornados pela API. Lembre-se que a CPFHub.io não bloqueia ao atingir o limite de consultas: volumes acima do plano contratado geram cobranças de R$0,15 por consulta adicional.

• Rate limit -- No plano gratuito, respeite o limite de 1 requisição a cada 2 segundos. No Pro, 1 requisição por segundo.

• Logs -- Registre todas as consultas realizadas para fins de auditoria e diagnóstico.

• Segurança da chave -- Armazene a chave de API em parâmetros do sistema ou variáveis de ambiente, nunca no código-fonte. A Receita Federal exige que dados de CPF sejam tratados com controles de acesso adequados em sistemas que emitem documentos fiscais.

Perguntas frequentes

A validação de CPF no ERP impede a emissão de NF-e com CPF inválido?

Sim, quando implementada corretamente. Ao validar o CPF antes de salvar o registro de cliente ou fornecedor, o ERP bloqueia cadastros com dados incorretos. Como a SEFAZ valida o CPF do destinatário no momento da autorização da NF-e, ter CPFs verificados antecipadamente elimina rejeições e retrabalho no setor fiscal.

Qual é o volume de consultas necessário para validar uma base de clientes existente?

Depende do tamanho da base. Para higienizar 1.000 registros, o plano Pro (1.000 consultas/mês por R$149) cobre a operação em um único mês. Para bases maiores, a CPFHub.io cobra R$0,15 por consulta adicional — a API não bloqueia ao atingir o limite, portanto o processo de atualização em massa pode ser planejado sem interrupções.

Como evitar que o ERP fique lento durante a validação em massa?

Use processamento em batch com intervalos entre requisições (1 a 2 segundos) para respeitar o rate limit. Em Odoo, utilize a fila de jobs do sistema; no ERPNext, crie um Scheduled Job no Frappe. Processe os registros em horários de baixo uso do ERP para minimizar o impacto na operação.

É necessário armazenar os dados retornados pela API no ERP?

Não é obrigatório, mas armazenar o nome retornado pela API (nome_cpf) facilita auditorias e a detecção de divergências entre o nome cadastrado e o nome real. Conforme a LGPD, armazene apenas o que for necessário para as finalidades declaradas e documente o tratamento. A ANPD orienta que dados pessoais devem ser mantidos apenas pelo tempo necessário.

Conclusão

Integrar a API de consulta de CPF da CPFHub.io ao Odoo ou ERPNext é uma forma direta de eliminar CPFs inválidos da base de dados, reduzir rejeições de NF-e e automatizar a conferência cadastral que hoje consome tempo da equipe administrativa.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a validar CPFs diretamente no seu ERP ainda hoje.