Como integrar validação de CPF em OutSystems com REST Consume

O OutSystems é uma das plataformas de desenvolvimento low-code mais adotadas no mundo corporativo, e integrar validação de CPF nela é direto: basta criar um REST Consume apontando para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key, mapear a resposta JSON em Structures e encapsular a lógica em uma Server Action reutilizável. A API responde em ~900ms e não bloqueia requisições além do limite — cobra R$0,15 por consulta extra, mantendo a aplicação no ar em qualquer pico de volume.

O que é REST Consume no OutSystems

O REST Consume é o mecanismo do OutSystems para integrar APIs REST externas. Ele permite:

• Definir endpoints, headers e parâmetros de forma visual.
• Mapear automaticamente as respostas JSON para estruturas (Structures) do OutSystems.
• Tratar erros e timeouts de forma declarativa.
• Reutilizar a integração em qualquer módulo da aplicação.

A configuração é feita no Service Studio, o IDE do OutSystems, e o consumo da API é exposto como uma Server Action reutilizável. Para orientações gerais sobre segurança em APIs REST, a documentação OutSystems detalha boas práticas de autenticação e tratamento de erros.

Configurando o REST Consume

Passo 1 -- Criar a integração REST

No Service Studio:

1. Acesse a aba Logic > Integrations > REST.
2. Clique com o botão direito e selecione Consume REST API > Add Single Method.
3. Configure:

Nome: CPFHub_ValidateCPF
URL: https://api.cpfhub.io/cpf/{CPFNumber}
HTTP Method: GET

Headers:
    - x-api-key: (Input Parameter)
    - Accept: application/json

URL Parameters:
    - CPFNumber: (Input Parameter, Text)

Timeout: 10 segundos

Passo 2 -- Definir a estrutura de resposta

Cole o JSON de exemplo para o OutSystems mapear automaticamente:

{
    "success": true,
    "data": {
    "cpf": "12345678909",
    "name": "NOME COMPLETO",
    "nameUpper": "NOME COMPLETO",
    "gender": "M",
    "birthDate": "01/01/1990",
    "day": "01",
    "month": "01",
    "year": "1990"
    }
}

O OutSystems criará automaticamente as Structures:

• CPFHubResponse (com campo success e data)
• CPFHubData (com campos cpf, name, gender, birthDate, etc.)

Criando a Server Action de validação

Crie uma Server Action que encapsula a lógica de validação:

-- Pseudo-código OutSystems (Server Action)

Server Action: ValidateCPF

Input Parameters:
    - CPF: Text

Output Parameters:
    - IsValid: Boolean
    - Name: Text
    - BirthDate: Text
    - Gender: Text
    - ErrorMessage: Text

Logic Flow:

1. [Assign] CleanCPF = Replace(Replace(Replace(CPF, ".", ""), "-", ""), " ", "")

2. [If] Length(CleanCPF) <> 11
    True -> [Assign] IsValid = False, ErrorMessage = "CPF deve conter 11 dígitos."
    False -> Continue

3. [REST Consume] CPFHub_ValidateCPF
    - CPFNumber = CleanCPF
    - x-api-key = Site.CPFHub_APIKey (Site Property)

4. [If] CPFHub_ValidateCPF.Response.success = True
    True ->
    [Assign]
    IsValid = True
    Name = CPFHub_ValidateCPF.Response.data.name
    BirthDate = CPFHub_ValidateCPF.Response.data.birthDate
    Gender = CPFHub_ValidateCPF.Response.data.gender
    False ->
    [Assign]
    IsValid = False
    ErrorMessage = "CPF não encontrado na base de dados."

5. [Exception Handler] AllExceptions
    [Assign]
    IsValid = False
    ErrorMessage = "Erro ao validar CPF. Tente novamente."

Criando a tela de validação

Estrutura da tela

No Service Studio, crie uma Web Screen com os seguintes elementos:

Screen: CPFValidation

Layout:
    Container (MainContent)
    |-- Form
    | |-- Input (CPFInput)
    | | Label: "CPF"
    | | Variable: Local.CPFValue
    | | InputMode: numeric
    | |
    | |-- Button (ValidateButton)
    | | Text: "Validar CPF"
    | | OnClick: ValidateCPFAction
    | |
    | |-- Container (FeedbackContainer)
    | | Visible: Local.ShowFeedback
    | | |-- If (IsValid)
    | | | True -> SuccessMessage
    | | | False -> ErrorMessage
    |
    |-- Container (ResultContainer)
    | Visible: Local.ShowResult
    | |-- Expression: Local.ResultName
    | |-- Expression: Local.ResultBirthDate
    | |-- Expression: Local.ResultGender

Screen Action para validação

-- Screen Action: ValidateCPFAction

1. [Assign] Local.ShowFeedback = True, Local.FeedbackText = "Validando..."

2. [Server Action] ValidateCPF
    CPF = Local.CPFValue

3. [If] ValidateCPF.IsValid
    True ->
    [Assign]
    Local.ShowResult = True
    Local.ResultName = ValidateCPF.Name
    Local.ResultBirthDate = ValidateCPF.BirthDate
    Local.ResultGender = ValidateCPF.Gender
    Local.FeedbackText = "CPF válido!"
    Local.FeedbackType = "success"
    False ->
    [Assign]
    Local.ShowResult = False
    Local.FeedbackText = ValidateCPF.ErrorMessage
    Local.FeedbackType = "error"

4. [Ajax Refresh] FeedbackContainer, ResultContainer

Implementando validação com JavaScript (Client Action)

Para validação em tempo real no Reactive Web, use uma Client Action com JavaScript:

// JavaScript node dentro de Client Action
var cpfInput = document.querySelector(
    "input[data-input][id*='CPFInput']"
);

if (cpfInput) {
    cpfInput.addEventListener("input", function () {
    var v = this.value.replace(/\D/g, "").slice(0, 11);
    if (v.length > 9)
    v = v.replace(
    /(\d{3})(\d{3})(\d{3})(\d{1,2})/,
    "$1.$2.$3-$4"
    );
    else if (v.length > 6)
    v = v.replace(/(\d{3})(\d{3})(\d{1,3})/, "$1.$2.$3");
    else if (v.length > 3)
    v = v.replace(/(\d{3})(\d{1,3})/, "$1.$2");
    this.value = v;
    });
}

Site Properties para configuração

Armazene a chave de API em uma Site Property para facilitar a gestão entre ambientes:

Site Property: CPFHub_APIKey
    Data Type: Text
    Default Value: ""
    Description: Chave de API do CPFHub.io

Configure valores diferentes para cada ambiente (Development, QA, Production) via Service Center.

Tratamento de erros e logging

Logging estruturado

-- Server Action: LogCPFValidation

Input Parameters:
    - CPF: Text
    - Success: Boolean
    - ResponseName: Text
    - ErrorMessage: Text

Logic:
1. [Create Record] CPFValidationLog
    - CPF = Left(CleanCPF, 3) + "****" + Right(CleanCPF, 2) -- Mascarar
    - Success = Success
    - ResponseName = ResponseName
    - ErrorMessage = ErrorMessage
    - UserID = GetUserId()
    - Timestamp = CurrDateTime()
    - IPAddress = GetIP()

Tabela de log

Entity: CPFValidationLog
    Attributes:
    - Id (Auto Number)
    - CPFMasked (Text, 11)
    - Success (Boolean)
    - ResponseName (Text, 200)
    - ErrorMessage (Text, 500)
    - UserID (User Identifier)
    - Timestamp (Date Time)
    - IPAddress (Text, 50)

Testando no OutSystems

Para testar a integração:

1. Configure a Site Property CPFHub_APIKey no Service Center.
2. Publique a aplicação (1-Click Publish).
3. Acesse a tela de validação de CPF.
4. Digite um CPF e clique em "Validar".
5. Verifique os logs na entidade CPFValidationLog.

Para testes automatizados, use o BDD Framework do OutSystems:

-- BDD Test: CPF Validation

Given: A valid CPF number "12345678909"
When: I call ValidateCPF Server Action
Then: IsValid should be True
And: Name should not be empty

Perguntas frequentes

Como configurar o REST Consume no OutSystems para autenticar com x-api-key?

No Service Studio, ao criar o REST Consume, adicione um header estático chamado x-api-key e defina seu valor como um Input Parameter do método ou como uma Site Property. A abordagem com Site Property é preferível em produção: permite trocar a chave por ambiente (Development, QA, Production) sem republicar o código. Configure o valor no Service Center de cada ambiente após o deploy.

A API CPFHub.io bloqueia chamadas quando o limite do plano é atingido?

Não. O plano gratuito oferece 50 consultas/mês e o plano Pro 1.000 consultas/mês por R$149. Ao ultrapassar o limite, a API continua respondendo e cobra R$0,15 por consulta adicional — sem retorno de erro 429 e sem interrupção do serviço. Isso evita que aplicações OutSystems em produção parem por conta de pico de volume inesperado.

Como reutilizar a integração de CPF em múltiplos módulos OutSystems?

Crie a Server Action ValidateCPF em um módulo de serviços compartilhados (Service Module) e exponha-a como Public. Os demais módulos da aplicação referenciam esse módulo e consomem a Server Action sem duplicar a integração REST. Essa arquitetura segue o padrão de separação de responsabilidades recomendado pela OutSystems para aplicações corporativas.

Como mascarar o CPF nos logs de auditoria sem perder rastreabilidade?

Armazene apenas os três primeiros e os dois últimos dígitos do CPF, substituindo os demais por asteriscos (ex.: 123****09). Isso preserva rastreabilidade suficiente para auditoria sem expor o dado completo em logs, alinhando ao princípio de minimização de dados da LGPD. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Conclusão

A integração do OutSystems com a API do CPFHub.io

Com tempo de resposta de aproximadamente 900ms, uptime de 99,9% e conformidade total com a LGPD, a CPFHub é a escolha ideal para aplicações OutSystems corporativas.

Cadastre-se em cpfhub.io