# Como integrar validação de CPF em OutSystems com REST Consume > Aprenda a integrar validação de CPF em aplicações OutSystems usando REST Consume para consumir a API da CPFHub. **Publicado:** 08/08/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-integrar-validacao-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](https://success.outsystems.com/documentation) 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: ```json { "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 // 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](https://www.gov.br/anpd) orienta que dados de identificação devem ser tratados com o princípio da necessidade. ### 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 A integração do OutSystems com a API do [**CPFHub.io**](https://www.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](https://www.cpfhub.io/)