# Como consumir API de CPF em Mendix com microflows e REST > Aprenda a consumir a API de CPF da CPFHub em Mendix usando microflows e integração REST para validação em aplicações low-code. **Publicado:** 09/08/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-consumir-api-de-cpf-em-mendix-com-microflows-e-rest --- Para validar CPF em aplicações Mendix, crie um Consumed REST Service apontando para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`, mapeie a resposta JSON em entidades do domínio e orquestre o fluxo em um microflow reutilizável. A API retorna nome, data de nascimento e gênero do titular em ~900ms, sem bloquear requisições que ultrapassem o plano — consultas extras são cobradas a R$0,15 cada. --- ## Conceitos fundamentais do Mendix ### Microflows Microflows são a unidade de lógica de negócio no Mendix. Executados no servidor, eles podem chamar APIs externas, manipular dados, tomar decisões e retornar resultados. São modelados visualmente no Mendix Studio Pro. ### Nanoflows Nanoflows são semelhantes aos microflows, mas executam no cliente (navegador ou dispositivo móvel). São úteis para validações rápidas antes de enviar dados ao servidor. ### Consumed REST Services O Mendix permite consumir APIs REST externas de forma declarativa, mapeando URLs, headers e estruturas de dados sem escrever código. Consulte a [documentação oficial do Mendix](https://docs.mendix.com) para referência completa sobre configuração de Consumed REST Services e Import Mappings. --- ## Configurando o Consumed REST Service ### Passo 1 -- Criar o serviço No Mendix Studio Pro: 1. Clique com o botão direito na pasta do módulo. 2. Selecione **Add other > Consumed REST Service**. 3. Configure: ``` Nome: CPFHub_Service Base URL: https://api.cpfhub.io -- Adicionar HTTP Header Header Name: x-api-key Value: (Constante) CPFHub_APIKey Header Name: Accept Value: application/json ``` ### Passo 2 -- Adicionar operação GET ``` Nome da Operação: ValidateCPF HTTP Method: GET Location: /cpf/{CPFNumber} -- Parâmetro de URL Nome: CPFNumber Tipo: String -- Timeout Request Timeout: 10000 (milissegundos) ``` --- ## Modelando o domínio Crie as entidades para mapear a resposta da API: ``` Entity: CPFResponse Attributes: - Success (Boolean) Association: - CPFResponse_CPFData (1-to-1) Entity: CPFData Attributes: - CPF (String, 11) - Name (String, 200) - NameUpper (String, 200) - Gender (String, 1) - BirthDate (String, 10) - Day (String, 2) - Month (String, 2) - Year (String, 4) ``` ### Import Mapping Crie um Import Mapping para converter o JSON da API nas entidades: ```json { "success": true, "data": { "cpf": "12345678909", "name": "NOME COMPLETO", "nameUpper": "NOME COMPLETO", "gender": "M", "birthDate": "01/01/1990", "day": "01", "month": "01", "year": "1990" } } ``` Mapeie `success` para `CPFResponse.Success` e os campos dentro de `data` para `CPFData`. --- ## Criando o microflow de validação O microflow principal orquestra todo o fluxo de validação: ``` Microflow: MF_ValidateCPF Input Parameters: - CPFInput (String) Return Type: CPFValidationResult (Non-persistent entity) Flow: 1. [Create Variable] CleanCPF = replaceAll(replaceAll(replaceAll($CPFInput, '.', ''), '-', ''), ' ', '') 2. [Decision] length($CleanCPF) = 11 False -> [Create Object] CPFValidationResult IsValid = false ErrorMessage = 'CPF deve conter 11 dígitos.' [End Event] Return CPFValidationResult 3. [Call REST Service] CPFHub_Service.ValidateCPF CPFNumber = $CleanCPF -- Store response in: $RESTResponse 4. [Decision] $RESTResponse/Success = true True -> [Create Object] CPFValidationResult IsValid = true Name = $RESTResponse/CPFResponse_CPFData/CPFData/Name BirthDate = $RESTResponse/CPFResponse_CPFData/CPFData/BirthDate Gender = $RESTResponse/CPFResponse_CPFData/CPFData/Gender False -> [Create Object] CPFValidationResult IsValid = false ErrorMessage = 'CPF não encontrado na base de dados.' 5. [End Event] Return CPFValidationResult Error Handler (Custom): [Create Object] CPFValidationResult IsValid = false ErrorMessage = 'Erro ao validar CPF. Tente novamente.' [End Event] Return CPFValidationResult ``` --- ## Entidade de resultado (Non-persistent) ``` Entity: CPFValidationResult (Non-persistent) Attributes: - IsValid (Boolean) - Name (String, 200) - BirthDate (String, 10) - Gender (String, 1) - ErrorMessage (String, 500) ``` --- ## Criando a página de validação ### Layout da página ``` Page: CPF_Validation_Page Layout: LayoutGrid (2 columns) Column 1: DataView (DataSource: CPFValidationInput object) |-- TextBox: CPF | Placeholder: "000.000.000-00" | |-- ActionButton: "Validar CPF" | On Click: Call Microflow MF_ValidateCPF_FromPage Column 2: DataView (DataSource: CPFValidationResult) Visibility: $Result/IsValid = true |-- TextBox (ReadOnly): Nome -> $Result/Name |-- TextBox (ReadOnly): Data de Nascimento -> $Result/BirthDate |-- TextBox (ReadOnly): Gênero -> $Result/Gender Container (Error Feedback) Visibility: $Result/IsValid = false AND $Result/ErrorMessage != empty |-- Text: $Result/ErrorMessage |-- Class: alert-danger ``` --- ## Nanoflow para máscara de CPF Crie um nanoflow que formata o CPF enquanto o usuário digita: ``` Nanoflow: NF_FormatCPF Input: CPFValue (String) Output: FormattedCPF (String) Flow: 1. [JavaScript Action] // Código JavaScript dentro do JavaScript Action var digits = $CPFValue.replace(/\D/g, '').slice(0, 11); var formatted = digits; if (digits.length > 9) { formatted = digits.replace( /(\d{3})(\d{3})(\d{3})(\d{1,2})/, '$1.$2.$3-$4' ); } else if (digits.length > 6) { formatted = digits.replace( /(\d{3})(\d{3})(\d{1,3})/, '$1.$2.$3' ); } else if (digits.length > 3) { formatted = digits.replace( /(\d{3})(\d{1,3})/, '$1.$2' ); } return formatted; ``` Conecte este nanoflow ao evento "On Change" do campo de CPF na página. --- ## Constantes e configuração Armazene a chave de API como uma constante do Mendix: ``` Constant: CPFHub_APIKey Type: String Default Value: SUA_CHAVE_DE_API -- Configure valores por ambiente via Mendix Developer Portal: -- Development: chave de teste -- Acceptance: chave de staging -- Production: chave de produção ``` --- ## Logging e auditoria Crie um microflow auxiliar para registrar consultas: ``` Microflow: MF_LogCPFQuery Input: CPF (String), Success (Boolean), ResponseName (String) Flow: 1. [Create Object] CPFQueryLog - CPFMasked = substring($CPF, 0, 3) + '****' + substring($CPF, 9, 2) - Success = $Success - ResponseName = $ResponseName - UserName = $currentSession/User/Name - Timestamp = [%CurrentDateTime%] 2. [Commit Object] CPFQueryLog ``` --- ## Validação local antes da chamada API Adicione validação de dígitos verificadores no nanoflow para economizar chamadas à API: ```javascript // JavaScript Action: JS_ValidateCPFDigits function validateCPF(cpf) { var digits = cpf.replace(/\D/g, ""); if (digits.length !== 11) return false; if (/^(\d)\1{10}$/.test(digits)) return false; var sum = 0; for (var i = 0; i < 9; i++) { sum += parseInt(digits.charAt(i)) * (10 - i); } var remainder = (sum * 10) % 11; if (remainder === 10) remainder = 0; if (remainder !== parseInt(digits.charAt(9))) return false; sum = 0; for (var i = 0; i < 10; i++) { sum += parseInt(digits.charAt(i)) * (11 - i); } remainder = (sum * 10) % 11; if (remainder === 10) remainder = 0; return remainder === parseInt(digits.charAt(10)); } return validateCPF($CPFValue); ``` --- ## Perguntas frequentes ### Como configurar a constante de API key no Mendix para diferentes ambientes? Crie uma Constant chamada `CPFHub_APIKey` no módulo e defina um valor padrão vazio. Em seguida, configure valores distintos para Development, Acceptance e Production no Mendix Developer Portal, em **Apps > Environments > Constants**. Assim a chave correta é carregada automaticamente em cada ambiente sem alterar o código do microflow. ### A API CPFHub.io retorna erro 429 quando o limite de consultas é atingido? Não. A API não bloqueia requisições ao atingir o limite mensal do plano. O plano gratuito inclui 50 consultas/mês e o plano Pro inclui 1.000 consultas/mês por R$149; ao ultrapassar qualquer um deles, cada consulta extra é cobrada a R$0,15 e a API continua respondendo normalmente. Isso evita falhas inesperadas nos microflows Mendix em produção. ### Por que usar validação local de dígitos antes de chamar a API? A validação matemática dos dígitos verificadores do CPF (algoritmo módulo 11) pode ser feita em um JavaScript Action sem custo de rede. Isso filtra CPFs com formato inválido antes mesmo de consumir uma consulta da API, reduzindo o volume cobrado e diminuindo a latência percebida pelo usuário quando o CPF é nitidamente incorreto. ### Como estruturar o Import Mapping para mapear o JSON da CPFHub corretamente? No Mendix Studio Pro, crie o Import Mapping a partir do JSON de exemplo da API. Mapeie o campo `success` para o atributo `CPFResponse.Success` e os campos dentro do objeto `data` (como `name`, `birthDate`, `gender`) para os atributos da entidade `CPFData`, associada a `CPFResponse` por uma associação 1-to-1. O Mendix gera o mapeamento automaticamente ao colar o JSON de exemplo na interface do Import Mapping. ### 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) - [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura) - [Autenticação em APIs REST: como garantir segurança na consulta de CPF](https://cpfhub.io/blog/autenticacao-apis-rest-seguranca-consulta-cpf) - [Como integrar validação de CPF em Power Automate para workflows corporativos](https://cpfhub.io/blog/como-integrar-validacao-cpf-power-automate-workflows-corporativos) --- ## Conclusão O Mendix, com seus microflows e integração REST nativa, oferece uma forma produtiva e visual de consumir a API do [**CPFHub.io**](https://www.cpfhub.io/) A API da CPFHub entrega respostas em aproximadamente 900ms, com uptime de 99,9% e conformidade total com a LGPD -- atributos essenciais para aplicações corporativas construídas em Mendix. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/)