# Como consumir API de CPF em Oracle APEX com PL/SQL e REST

> Guia para consumir a API de CPF da CPFHub em Oracle APEX usando PL/SQL e REST Data Sources para validação em aplicações corporativas.

**Publicado:** 06/08/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-api-de-cpf-em-oracle-apex-com-plsql-e-rest

---


O Oracle APEX (Application Express) é a plataforma de desenvolvimento low-code da Oracle, amplamente utilizada em ambientes corporativos para construir aplicações web conectadas a bancos de dados Oracle. Para integrar validação de CPF em formulários de cadastro e processos internos, basta configurar a ACL de rede e chamar a API da CPFHub via `APEX_WEB_SERVICE` ou um REST Data Source declarativo. A API retorna nome, data de nascimento e gênero do titular em ~900ms, sem bloquear requisições que ultrapassem o plano contratado.

---

## Pré-requisitos no Oracle APEX

Antes de fazer chamadas HTTP externas, o servidor Oracle precisa de permissão para acessar hosts externos. Configure a ACL (Access Control List):

```sql
-- Executar como SYSDBA ou com privilégios de DBA
BEGIN
 DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
 host => 'api.cpfhub.io',
 ace => xs$ace_type(
 privilege_list => xs$name_list('connect', 'resolve'),
 principal_name => 'APEX_230100', -- Ajuste para sua versão do APEX
 principal_type => xs_acl.ptype_db
 )
 );
END;
/

-- Configurar wallet para HTTPS (se necessário)
BEGIN
 DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
 host => 'api.cpfhub.io',
 lower_port => 443,
 upper_port => 443,
 ace => xs$ace_type(
 privilege_list => xs$name_list('connect'),
 principal_name => 'APEX_230100',
 principal_type => xs_acl.ptype_db
 )
 );
END;
/
```

---

## Abordagem 1 -- PL/SQL com APEX_WEB_SERVICE

### Criando a função de validação

```sql
CREATE OR REPLACE FUNCTION fn_validar_cpf(
 p_cpf IN VARCHAR2
) RETURN CLOB
IS
 l_cpf_limpo VARCHAR2(11);
 l_url VARCHAR2(200);
 l_response CLOB;
 l_api_key VARCHAR2(100);
BEGIN
 -- Limpar CPF
 l_cpf_limpo := REGEXP_REPLACE(p_cpf, '[^0-9]', '');

 IF LENGTH(l_cpf_limpo) != 11 THEN
 RETURN '{"success": false, "message": "CPF deve conter 11 dígitos."}';
 END IF;

 -- Buscar chave de API de tabela de configuração
 SELECT valor INTO l_api_key
 FROM app_config
 WHERE chave = 'CPFHUB_API_KEY';

 l_url := 'https://api.cpfhub.io/cpf/' || l_cpf_limpo;

 -- Configurar headers
 APEX_WEB_SERVICE.G_REQUEST_HEADERS.DELETE;
 APEX_WEB_SERVICE.G_REQUEST_HEADERS(1).NAME := 'x-api-key';
 APEX_WEB_SERVICE.G_REQUEST_HEADERS(1).VALUE := l_api_key;
 APEX_WEB_SERVICE.G_REQUEST_HEADERS(2).NAME := 'Accept';
 APEX_WEB_SERVICE.G_REQUEST_HEADERS(2).VALUE := 'application/json';

 -- Fazer requisição GET com timeout
 l_response := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
 p_url => l_url,
 p_http_method => 'GET',
 p_transfer_timeout => 10
 );

 RETURN l_response;

EXCEPTION
 WHEN OTHERS THEN
 RETURN '{"success": false, "message": "Erro: ' ||
 REPLACE(SQLERRM, '"', '\"') || '"}';
END fn_validar_cpf;
/
```

### Parseando a resposta JSON

```sql
CREATE OR REPLACE PROCEDURE sp_processar_cpf(
 p_cpf IN VARCHAR2,
 p_nome OUT VARCHAR2,
 p_nascimento OUT VARCHAR2,
 p_genero OUT VARCHAR2,
 p_sucesso OUT BOOLEAN,
 p_mensagem OUT VARCHAR2
)
IS
 l_response CLOB;
 l_json JSON_OBJECT_T;
 l_data JSON_OBJECT_T;
 l_success BOOLEAN;
BEGIN
 l_response := fn_validar_cpf(p_cpf);

 l_json := JSON_OBJECT_T.PARSE(l_response);
 l_success := l_json.GET_BOOLEAN('success');

 IF l_success THEN
 l_data := l_json.GET_OBJECT('data');
 p_nome := l_data.GET_STRING('name');
 p_nascimento := l_data.GET_STRING('birthDate');
 p_genero := l_data.GET_STRING('gender');
 p_sucesso := TRUE;
 p_mensagem := 'CPF válido';
 ELSE
 p_sucesso := FALSE;
 p_mensagem := NVL(
 l_json.GET_STRING('message'),
 'CPF não encontrado'
 );
 END IF;

EXCEPTION
 WHEN OTHERS THEN
 p_sucesso := FALSE;
 p_mensagem := 'Erro ao processar resposta: ' || SQLERRM;
END sp_processar_cpf;
/
```

---

## Abordagem 2 -- REST Data Sources

O Oracle APEX permite configurar REST Data Sources de forma declarativa. Isso facilita o uso em relatórios, formulários e processos.

### Configurando o REST Data Source

1. No APEX, acesse **Shared Components > REST Data Sources**.
2. Clique em **Create** e configure:

```
Nome: CPFHub Validator
Tipo: Simple HTTP
URL Endpoint: https://api.cpfhub.io/cpf/
HTTP Method: GET

-- Em "Operations" adicione:
Nome da Operação: GET_CPF
URL Pattern: {cpf}
HTTP Method: GET

-- Em "HTTP Headers" adicione:
Header 1: x-api-key = {sua_chave}
Header 2: Accept = application/json

-- Em "Parameters" adicione:
Nome: cpf
Tipo: URL Pattern
Direction: In
```

### Usando em um processo de página

```sql
-- Processo PL/SQL na página APEX
DECLARE
 l_cpf VARCHAR2(11);
 l_response CLOB;
 l_json JSON_OBJECT_T;
 l_data JSON_OBJECT_T;
BEGIN
 l_cpf := REGEXP_REPLACE(:P10_CPF, '[^0-9]', '');

 -- Consultar via REST Data Source
 l_response := APEX_EXEC.EXECUTE_REST_SOURCE(
 p_static_id => 'cpfhub_validator',
 p_operation => 'GET_CPF',
 p_url_pattern_values => APEX_EXEC.T_PARAMETERS(
 1 => APEX_EXEC.T_PARAMETER(
 name => 'cpf',
 value => l_cpf
 )
 )
 );

 l_json := JSON_OBJECT_T.PARSE(l_response);

 IF l_json.GET_BOOLEAN('success') THEN
 l_data := l_json.GET_OBJECT('data');

 :P10_NOME := l_data.GET_STRING('name');
 :P10_NASCIMENTO := l_data.GET_STRING('birthDate');
 :P10_GENERO := l_data.GET_STRING('gender');
 :P10_STATUS := 'VALIDO';
 ELSE
 :P10_STATUS := 'INVALIDO';
 :P10_NOME := NULL;
 END IF;
END;
```

---

## Validação dinâmica com Dynamic Action

Para validar o CPF em tempo real enquanto o usuário digita, use Dynamic Actions do APEX:

1. No campo de CPF (P10_CPF), crie uma Dynamic Action:
 - **Event**: Change
 - **Action**: Execute PL/SQL Code
 - **Items to Submit**: P10_CPF
 - **Items to Return**: P10_NOME, P10_NASCIMENTO, P10_GENERO, P10_STATUS

```sql
-- Código PL/SQL da Dynamic Action
DECLARE
 l_cpf VARCHAR2(11);
 l_nome VARCHAR2(200);
 l_nasc VARCHAR2(20);
 l_genero VARCHAR2(20);
 l_ok BOOLEAN;
 l_msg VARCHAR2(500);
BEGIN
 l_cpf := REGEXP_REPLACE(:P10_CPF, '[^0-9]', '');

 IF LENGTH(l_cpf) = 11 THEN
 sp_processar_cpf(
 p_cpf => l_cpf,
 p_nome => l_nome,
 p_nascimento => l_nasc,
 p_genero => l_genero,
 p_sucesso => l_ok,
 p_mensagem => l_msg
 );

 IF l_ok THEN
 :P10_NOME := l_nome;
 :P10_NASCIMENTO := l_nasc;
 :P10_GENERO := l_genero;
 :P10_STATUS := 'CPF Válido';
 ELSE
 :P10_STATUS := l_msg;
 END IF;
 END IF;
END;
```

---

## Tabela de log para auditoria

Em ambientes corporativos, registrar todas as consultas de CPF é uma boa prática de governança e conformidade com a LGPD:

```sql
CREATE TABLE cpf_audit_log (
 id NUMBER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 cpf VARCHAR2(11) NOT NULL,
 sucesso CHAR(1) DEFAULT 'N',
 nome VARCHAR2(200),
 usuario VARCHAR2(100),
 ip_address VARCHAR2(50),
 data_hora TIMESTAMP DEFAULT SYSTIMESTAMP,
 resposta CLOB
);

-- Trigger ou procedimento para inserir log
CREATE OR REPLACE PROCEDURE sp_log_consulta_cpf(
 p_cpf IN VARCHAR2,
 p_sucesso IN BOOLEAN,
 p_nome IN VARCHAR2,
 p_resposta IN CLOB
)
IS
BEGIN
 INSERT INTO cpf_audit_log (cpf, sucesso, nome, usuario, ip_address, resposta)
 VALUES (
 REGEXP_REPLACE(p_cpf, '[^0-9]', ''),
 CASE WHEN p_sucesso THEN 'S' ELSE 'N' END,
 p_nome,
 V('APP_USER'),
 OWA_UTIL.GET_CGI_ENV('REMOTE_ADDR'),
 p_resposta
 );
 COMMIT;
END;
/
```

---

## Máscara de CPF no frontend APEX

Adicione formatação automática ao campo de CPF usando JavaScript inline no APEX. Para referência sobre boas práticas de segurança em chamadas REST, consulte a [documentação oficial do Oracle APEX](https://apex.oracle.com/en/learn/documentation):

```javascript
// Execute via Dynamic Action (Execute JavaScript Code) no evento Page Load
apex.jQuery("#P10_CPF").on("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;
});
```

---

## Perguntas frequentes

### Como configurar a ACL no Oracle para chamar a API de CPF externamente?

A ACL (Access Control List) do Oracle precisa ser configurada via `DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE` para que o servidor consiga realizar chamadas HTTPS ao host `api.cpfhub.io`. O procedimento deve ser executado por um DBA ou usuário com privilégio equivalente, e é necessário liberar as portas 80 e 443. Sem isso, `APEX_WEB_SERVICE.MAKE_REST_REQUEST` retorna um erro de conexão recusada.

### Qual a diferença entre usar APEX_WEB_SERVICE e REST Data Sources no APEX?

`APEX_WEB_SERVICE` é uma abordagem programática via PL/SQL — oferece maior controle, mas exige mais código. Os REST Data Sources são declarativos: você configura visualmente no APEX e reaproveita a integração em relatórios, formulários e processos sem escrever SQL adicional. Para consultas de CPF disparadas por eventos de formulário, `APEX_WEB_SERVICE` costuma ser mais direto; para exibir dados em relatórios reativos, REST Data Sources são mais produtivos.

### A API CPFHub.io bloqueia requisições quando o limite mensal é atingido?

Não. Quando o plano gratuito (50 consultas/mês) ou o plano Pro (1.000 consultas/mês por R$149) é esgotado, a API continua respondendo normalmente e cobra R$0,15 por consulta adicional. Não há bloqueio nem retorno de erro 429. Isso garante que aplicações Oracle APEX em produção não parem por conta de pico de volume.

### Como armazenar a API key com segurança em uma aplicação Oracle APEX?

A prática recomendada é guardar a chave em uma tabela de configuração com acesso restrito por perfil de banco (`app_config`), separada dos dados da aplicação. Nunca inclua a chave diretamente no código PL/SQL ou em constantes de aplicação visíveis no APEX Builder. Em ambientes com Oracle Vault ou AWS Secrets Manager integrado ao banco, prefira buscar a chave dinamicamente via wrapper PL/SQL.

### 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 criar um SDK interno para padronizar consultas de CPF na empresa](https://cpfhub.io/blog/como-criar-sdk-interno-padronizar-consultas-cpf-empresa)

---

## Conclusão

O Oracle APEX, combinado com PL/SQL e REST Data Sources, oferece múltiplas formas de integrar a validação de CPF via 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 -- essencial para aplicações corporativas em Oracle APEX.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/)