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.

Redação CPFHub.io
Redação CPFHub.io
··7 min de leitura
Como consumir API de CPF em Oracle APEX com PL/SQL 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):

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

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

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

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

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:

// 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.


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

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

CPFHub.io

Pronto para integrar a API?

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

Redação CPFHub.io

Sobre a redação

Redação CPFHub.io

Time editorial especializado em APIs de CPF, identidade digital e compliance no mercado brasileiro. Produzimos guias técnicos, análises regulatórias e tutoriais sobre LGPD e KYC para desenvolvedores e líderes de produto.

WhatsAppFale conosco via WhatsApp