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. Esgotar os 50 créditos do plano Grátis faz a API devolver HTTP 403, "Limite de créditos excedido", e pausar novas consultas. Nos planos pagos, havendo excedente, ele entra na fatura seguinte conforme a página de preços. O ritmo por minuto, se ultrapassado, gera HTTP 429 com Retry-After.

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

Clique com o botão direito na pasta do módulo.
Selecione Add other > Consumed REST Service.
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:

{
    "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 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 misture os dois limites. Estourar as requisições por minuto devolve HTTP 429 e o header Retry-After. Esgotar os créditos do mês, no plano Grátis, devolve HTTP 403 com "Limite de créditos excedido" e pausa as consultas; nos planos pagos pode haver excedente, descrito na página de preços.

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.

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

A API da CPFHub entrega respostas em ~150 ms, 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

CPFHub.io

Pronto para integrar a API?

50 créditos gratuitos para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

Começar grátis Ver documentação

Como consumir API de CPF em Mendix com microflows e REST