API de CPF: diferença entre consulta sincrona e assincrona

A diferença entre consulta sincrona e assincrona em uma API de CPF define como sua aplicação lida com o tempo de espera da resposta — e a escolha certa pode impactar tanto a experiência do usuário quanto a escalabilidade do sistema. A CPFHub.io suporta as duas abordagens com latência média de ~900ms, permitindo integrar o modelo que melhor se adapta ao seu fluxo sem precisar trocar de provedor.

Introdução

Ao integrar uma API de consulta de CPF, uma das decisões arquiteturais mais importantes e definir se a chamada sera sincrona ou assincrona. Essa escolha impacta diretamente a experiência do usuário, a resiliencia do sistema e a capacidade de processar grandes volumes.

Consulta sincrona

Na abordagem sincrona, a aplicação faz a chamada a API e aguarda a resposta antes de continuar o processamento. O fluxo e bloqueante -- o usuário espera até que o resultado esteja disponível.

Fluxo sincrono

1. Usuário envia o CPF.
2. Backend chama a API da CPFHub.io.
3. Backend aguarda a resposta (~900ms).
4. Backend retorna o resultado ao usuário.

Exemplo em Python (sincrono)

import requests

def validar_cpf_sincrono(cpf):
    url = f'https://api.cpfhub.io/cpf/{cpf}'
    headers = {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    }

    response = requests.get(url, headers=headers, timeout=15)

    if response.status_code == 200:
    data = response.json()
    if data.get('success'):
    return {
    'valido': True,
    'nome': data['data']['name'],
    'genero': data['data']['gender']
    }

    return {'valido': False, 'nome': None, 'genero': None}

# O codigo bloqueia aqui ate a resposta chegar
resultado = validar_cpf_sincrono('12345678900')
print(resultado)

Quando usar sincrono

• Checkout e pagamento -- O usuário espera a validação para prosseguir.

• Onboarding interativo -- O formulario depende da resposta para o próximo passo.

• Validação em tempo real -- Feedback imediato e necessário.

Consulta assincrona

Na abordagem assincrona, a aplicação dispara a chamada e continua o processamento sem esperar a resposta. O resultado e tratado quando fica disponível, via callback, polling ou fila de mensagens.

Fluxo assincrono

1. Usuário envia o CPF.
2. Backend enfileira a consulta e retorna imediatamente ("processando").
3. Worker consome a fila e chama a API da CPFHub.io.
4. Worker armazena o resultado.
5. Aplicação notifica o usuário ou atualiza a interface.

Exemplo em Python (assincrono com asyncio)

import aiohttp
import asyncio

async def validar_cpf_assincrono(cpf):
    url = f'https://api.cpfhub.io/cpf/{cpf}'
    headers = {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    }

    async with aiohttp.ClientSession() as session:
    async with session.get(url, headers=headers, timeout=aiohttp.ClientTimeout(total=15)) as response:
    if response.status == 200:
    data = await response.json()
    if data.get('success'):
    return {
    'valido': True,
    'nome': data['data']['name'],
    'genero': data['data']['gender']
    }

    return {'valido': False, 'nome': None, 'genero': None}

# Nao bloqueia -- pode executar outras tarefas em paralelo
async def main():
    tarefa1 = validar_cpf_assincrono('12345678900')
    tarefa2 = validar_cpf_assincrono('98765432100')
    resultados = await asyncio.gather(tarefa1, tarefa2)
    for r in resultados:
    print(r)

asyncio.run(main())

Exemplo em Node.js (assincrono com fila)

const Queue = require('bull');

const filaConsulta = new Queue('consulta-cpf', {
    redis: { host: 'localhost', port: 6379 }
});

// Produtor: enfileira a consulta
async function solicitarValidacao(cpf, callbackUrl) {
    await filaConsulta.add({
    cpf,
    callbackUrl,
    tentativa: 1
    });
    return { status: 'enfileirado', cpf };
}

// Consumidor: processa a fila
filaConsulta.process(async (job) => {
    const { cpf, callbackUrl } = job.data;

    const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
    method: 'GET',
    headers: {
    'x-api-key': process.env.CPFHUB_API_KEY,
    'Accept': 'application/json'
    },
    signal: AbortSignal.timeout(15000)
    });

    const data = await response.json();

    // Notificar via callback
    await fetch(callbackUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ cpf, resultado: data }),
    signal: AbortSignal.timeout(10000)
    });

    return data;
});

Quando usar assincrono

• Processamento em lote -- Validar centenas ou milhares de CPFs.

• Análise de crédito em background -- O resultado não e necessário imediatamente.

• Atualização cadastral periódica -- Processos agendados sem interação do usuário.

• Fluxos com multiplas APIs -- Orquestrar chamadas a diferentes serviços em paralelo.

Comparação detalhada

Modelo híbrido

Na prática, a maioria dos sistemas combina as duas abordagens:

• Sincrono para o primeiro cadastro do usuário (feedback imediato).

• Assincrono para revalidacao periódica da base de clientes.

• Sincrono com fallback -- Tenta sincrono; se falhar por timeout, enfileira para assincrono.

import requests

def validar_cpf_hibrido(cpf, fila):
    try:
    response = requests.get(
    f'https://api.cpfhub.io/cpf/{cpf}',
    headers={
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    },
    timeout=5 # timeout agressivo para sincrono
    )
    if response.status_code == 200:
    return response.json()
    except requests.exceptions.Timeout:
    pass

    # Fallback: enfileirar para processamento assincrono
    fila.enfileirar({'cpf': cpf, 'origem': 'fallback_timeout'})
    return {'status': 'processando', 'cpf': cpf}

Escolhendo o modelo certo

• Se o usuário esta esperando na tela, use sincrono.

• Se são mais de 10 CPFs por vez, use assincrono.

• Se o processo pode falhar e ser retentado, use assincrono com fila.

• Se precisa de latência mínima e fallback, use híbrido.

Perguntas frequentes

O que é necessário para implementar validação de CPF neste contexto?

A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação.

A API CPFHub.io funciona para todos os volumes de consulta?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

A escolha entre consulta sincrona e assincrona depende do contexto do seu fluxo. Entender as vantagens de cada abordagem e combinar as duas quando necessário resulta em uma integração mais resiliente, escalável e com melhor experiência para o usuário.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.