# Como integrar API de CPF em ERPs open source (Odoo, ERPNext) > Aprenda a integrar a API de consulta de CPF da CPFHub.io em ERPs open source como Odoo e ERPNext com exemplos práticos de código. **Publicado:** 09/08/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/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: ```bash 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: ```json { "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. ```python 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). ```python 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: ```python 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 | Cenário | Volume estimado | Plano recomendado | | --- | --- | --- | | Pequena empresa (até 50 clientes/mês) | Até 50 consultas | Gratuito (R$ 0) | | Média empresa (até 1.000 clientes/mês) | Até 1.000 consultas | Pro (R$ 149/mês) | | Grande empresa ou múltiplas filiais | Acima de 1.000 consultas | Corporativo (sob consulta) | --- ## 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](https://www.gov.br/receitafederal) 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](https://www.gov.br/anpd) orienta que dados pessoais devem ser mantidos apenas pelo tempo necessário. ### Leia também - [Como consumir API de CPF em n8n para automações self-hosted](https://cpfhub.io/blog/como-consumir-api-cpf-n8n-automacoes-self-hosted) - [Como consumir API de CPF em Google Apps Script para automações no Google Sheets](https://cpfhub.io/blog/como-consumir-api-cpf-google-apps-script-automacoes-google-sheets) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) --- ## Conclusão Integrar a API de consulta de CPF da [**CPFHub.io**](https://www.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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a validar CPFs diretamente no seu ERP ainda hoje.