Validação de CPF em Unity com C#

Para integrar validação de CPF em um projeto Unity com C#, use o UnityWebRequest para chamar GET https://api.cpfhub.io/cpf/{CPF} com o header x-api-key e deserialize a resposta JSON com JsonUtility. O UnityWebRequest é a classe nativa do Unity para requisições HTTP e garante compatibilidade com Android, iOS, WebGL e plataformas desktop sem dependências externas. A API da CPFHub.io responde em ~900ms, tornando a validação viável em telas de cadastro, plataformas de treinamento gamificado e sistemas com recompensas que exigem identificação do usuário. Consulte a documentação oficial do Unity para referência completa do UnityWebRequest.

1. Pré-requisitos

Unity 2022.3 LTS ou superior.
Conhecimento básico de C# e Coroutines do Unity.
Uma conta gratuita na CPFHub.io

2. Crie as classes de dados

Defina classes serializáveis para deserializar a resposta JSON da API:

// Scripts/Models/CpfResponse.cs
using System;

[Serializable]
public class CpfResponse
{
    public bool success;
    public CpfData data;
}

[Serializable]
public class CpfData
{
    public string cpf;
    public string name;
    public string nameUpper;
    public string gender;
    public string birthDate;
    public int day;
    public int month;
    public int year;
}

3. Crie o serviço de consulta

Implemente o serviço usando UnityWebRequest com Coroutines:

// Scripts/Services/CpfHubService.cs
using System;
using System.Collections;
using System.Text.RegularExpressions;
using UnityEngine;
using UnityEngine.Networking;

public class CpfHubService : MonoBehaviour
{
    [Header("Configurações da API")]
    [SerializeField] private string apiKey = "SUA_CHAVE_DE_API";
    [SerializeField] private string baseUrl = "https://api.cpfhub.io";
    [SerializeField] private int timeoutSeconds = 5;

    public delegate void OnCpfConsultado(CpfData dados);
    public delegate void OnCpfErro(string mensagemErro, int statusCode);

    public void ConsultarCpf(string cpf, OnCpfConsultado onSucesso, OnCpfErro onErro)
    {
    string cpfLimpo = Regex.Replace(cpf, @"\D", "");

    if (cpfLimpo.Length != 11)
    {
    onErro?.Invoke("CPF deve conter exatamente 11 dígitos.", 400);
    return;
    }

    StartCoroutine(ConsultarCpfCoroutine(cpfLimpo, onSucesso, onErro));
    }

    private IEnumerator ConsultarCpfCoroutine(
    string cpfLimpo,
    OnCpfConsultado onSucesso,
    OnCpfErro onErro)
    {
    string url = $"{baseUrl}/cpf/{cpfLimpo}";

    using (UnityWebRequest request = UnityWebRequest.Get(url))
    {
    request.SetRequestHeader("x-api-key", apiKey);
    request.SetRequestHeader("Accept", "application/json");
    request.timeout = timeoutSeconds;

    Debug.Log($"[CpfHub] Consultando CPF: {cpfLimpo}");

    yield return request.SendWebRequest();

    if (request.result == UnityWebRequest.Result.ConnectionError)
    {
    Debug.LogError($"[CpfHub] Erro de conexão: {request.error}");
    onErro?.Invoke($"Erro de conexão: {request.error}", 502);
    yield break;
    }

    if (request.result == UnityWebRequest.Result.ProtocolError)
    {
    int statusCode = (int)request.responseCode;
    string mensagem = statusCode switch
    {
    400 => "CPF com formato inválido.",
    401 => "Chave de API inválida ou ausente.",
    404 => "CPF não encontrado na base de dados.",
    _ => $"Erro HTTP {statusCode}."
    };

    Debug.LogWarning($"[CpfHub] {mensagem}");
    onErro?.Invoke(mensagem, statusCode);
    yield break;
    }

    string jsonResponse = request.downloadHandler.text;

    try
    {
    CpfResponse response = JsonUtility.FromJson<CpfResponse>(jsonResponse);

    if (response.success && response.data != null)
    {
    Debug.Log($"[CpfHub] CPF encontrado: {response.data.name}");
    onSucesso?.Invoke(response.data);
    }
    else
    {
    onErro?.Invoke("Resposta inesperada da API.", 500);
    }
    }
    catch (Exception ex)
    {
    Debug.LogError($"[CpfHub] Erro ao parsear JSON: {ex.Message}");
    onErro?.Invoke("Erro ao processar resposta da API.", 500);
    }
    }
    }
}

4. Crie o componente de UI

Implemente a interface de usuário no Unity com o sistema de UI Canvas:

// Scripts/UI/CpfConsultaUI.cs
using UnityEngine;
using UnityEngine.UI;
using TMPro;

public class CpfConsultaUI : MonoBehaviour
{
    [Header("Referências de UI")]
    [SerializeField] private TMP_InputField cpfInput;
    [SerializeField] private Button consultarButton;
    [SerializeField] private TextMeshProUGUI resultadoText;
    [SerializeField] private GameObject loadingIndicator;
    [SerializeField] private GameObject resultadoPanel;
    [SerializeField] private GameObject erroPanel;
    [SerializeField] private TextMeshProUGUI erroText;

    [Header("Serviço")]
    [SerializeField] private CpfHubService cpfService;

    private void Start()
    {
    consultarButton.onClick.AddListener(OnConsultarClick);
    cpfInput.onValueChanged.AddListener(AplicarMascaraCpf);
    loadingIndicator.SetActive(false);
    resultadoPanel.SetActive(false);
    erroPanel.SetActive(false);
    }

    private void OnConsultarClick()
    {
    string cpf = cpfInput.text.Trim();
    if (string.IsNullOrEmpty(cpf))
    {
    MostrarErro("Digite um CPF.");
    return;
    }

    consultarButton.interactable = false;
    loadingIndicator.SetActive(true);
    resultadoPanel.SetActive(false);
    erroPanel.SetActive(false);

    cpfService.ConsultarCpf(cpf, OnSucesso, OnErro);
    }

    private void OnSucesso(CpfData dados)
    {
    loadingIndicator.SetActive(false);
    consultarButton.interactable = true;
    resultadoPanel.SetActive(true);

    resultadoText.text = $"<b>Nome:</b> {dados.name}\n" +
    $"<b>CPF:</b> {dados.cpf}\n" +
    $"<b>Genero:</b> {dados.gender}\n" +
    $"<b>Nascimento:</b> {dados.birthDate}";
    }

    private void OnErro(string mensagem, int statusCode)
    {
    loadingIndicator.SetActive(false);
    consultarButton.interactable = true;
    MostrarErro(mensagem);
    }

    private void MostrarErro(string mensagem)
    {
    erroPanel.SetActive(true);
    resultadoPanel.SetActive(false);
    erroText.text = mensagem;
    }

    private void AplicarMascaraCpf(string valor)
    {
    string numeros = System.Text.RegularExpressions.Regex.Replace(valor, @"\D", "");
    if (numeros.Length > 11) numeros = numeros.Substring(0, 11);

    string formatado = numeros;
    if (numeros.Length > 9)
    formatado = $"{numeros.Substring(0, 3)}.{numeros.Substring(3, 3)}.{numeros.Substring(6, 3)}-{numeros.Substring(9)}";
    else if (numeros.Length > 6)
    formatado = $"{numeros.Substring(0, 3)}.{numeros.Substring(3, 3)}.{numeros.Substring(6)}";
    else if (numeros.Length > 3)
    formatado = $"{numeros.Substring(0, 3)}.{numeros.Substring(3)}";

    cpfInput.onValueChanged.RemoveListener(AplicarMascaraCpf);
    cpfInput.text = formatado;
    cpfInput.caretPosition = formatado.Length;
    cpfInput.onValueChanged.AddListener(AplicarMascaraCpf);
    }
}

5. Versão com async/await (Unity 2023+)

Para versões mais recentes do Unity que suportam Awaitable, use a versão assíncrona:

// Scripts/Services/CpfHubServiceAsync.cs
using System;
using System.Text.RegularExpressions;
using UnityEngine;
using UnityEngine.Networking;

public class CpfHubServiceAsync : MonoBehaviour
{
    [SerializeField] private string apiKey = "SUA_CHAVE_DE_API";
    [SerializeField] private string baseUrl = "https://api.cpfhub.io";
    [SerializeField] private int timeoutSeconds = 5;

    public async Awaitable<CpfData> ConsultarCpfAsync(string cpf)
    {
    string cpfLimpo = Regex.Replace(cpf, @"\D", "");

    if (cpfLimpo.Length != 11)
    throw new ArgumentException("CPF deve conter exatamente 11 dígitos.");

    string url = $"{baseUrl}/cpf/{cpfLimpo}";

    using (UnityWebRequest request = UnityWebRequest.Get(url))
    {
    request.SetRequestHeader("x-api-key", apiKey);
    request.SetRequestHeader("Accept", "application/json");
    request.timeout = timeoutSeconds;

    await request.SendWebRequest();

    if (request.result != UnityWebRequest.Result.Success)
    {
    int statusCode = (int)request.responseCode;
    string mensagem = statusCode switch
    {
    400 => "CPF com formato inválido.",
    401 => "Chave de API inválida.",
    404 => "CPF não encontrado.",
    _ => $"Erro: {request.error}"
    };
    throw new Exception(mensagem);
    }

    CpfResponse response = JsonUtility.FromJson<CpfResponse>(request.downloadHandler.text);

    if (response.success && response.data != null)
    return response.data;

    throw new Exception("Resposta inesperada da API.");
    }
    }
}

6. Configure a cena

Para montar a interface no Unity Editor:

Crie um Canvas com os elementos de UI (InputField, Button, Text, Panels).
Adicione um GameObject vazio e anexe o script CpfHubService.
Adicione o script CpfConsultaUI a outro GameObject e conecte as referências no Inspector.
Configure a API key no componente CpfHubService via Inspector ou ScriptableObject.

7. Boas práticas

UnityWebRequest -- Use UnityWebRequest em vez de HttpClient para garantir compatibilidade com todas as plataformas suportadas pelo Unity.
Coroutines vs Async -- Use Coroutines para compatibilidade ampla ou Awaitable para projetos com Unity 2023+.
Timeout -- Configure o timeout do UnityWebRequest para 5 segundos, adequado ao tempo de resposta de ~900ms da API.
Segurança -- Em builds de produção, use ScriptableObjects ou Addressables para configurar a API key fora do código-fonte. Considere um backend intermediário para projetos públicos.
Thread principal -- Callbacks do UnityWebRequest sempre executam na thread principal, seguro para atualizar a UI.
LGPD -- A API da CPFHub.io é 100% compatível com a LGPD. Em aplicações gamificadas, informe os usuários sobre o tratamento de dados pessoais.

Perguntas frequentes

Por que usar UnityWebRequest em vez de HttpClient no Unity?

O UnityWebRequest é a escolha correta para projetos Unity porque opera no loop de coroutines da engine, garantindo compatibilidade com Android, iOS, WebGL e plataformas de console. O HttpClient padrão do .NET pode causar problemas de threading e não suporta todas as plataformas alvo do Unity — especialmente WebGL, que tem restrições rígidas de rede.

Qual o tempo de resposta esperado da API da CPFHub.io no Unity?

A latência típica é de ~900ms. O timeout do UnityWebRequest está configurado para 5 segundos neste guia, o que dá margem suficiente para variações de rede sem travar a coroutine indefinidamente. Em aplicações onde o usuário aguarda visualmente, exiba um indicador de carregamento durante esse intervalo.

O que acontece quando o limite de consultas do plano gratuito é atingido?

A API não bloqueia nem retorna erro 429. O plano gratuito inclui 50 consultas por mês; ao ultrapassá-las, cada consulta adicional é cobrada automaticamente a R$0,15. O plano Pro oferece 1.000 consultas por R$149/mês com o mesmo modelo — sem interrupção do serviço durante o excedente.

Como proteger a API key em builds de produção do Unity?

Nunca inclua a API key diretamente no código-fonte de uma build pública, pois ela fica exposta no binário. A abordagem recomendada é criar um endpoint próprio no seu backend que recebe o CPF, faz a consulta à CPFHub.io com a chave armazenada no servidor e retorna o resultado ao Unity. Para builds internas, ScriptableObjects com acesso restrito ou variáveis de ambiente no CI/CD são alternativas viáveis.

Conclusão

Integrar a API da CPFHub.io

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.

Começar grátis Ver documentação

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.

Como integrar validação de CPF em Unity para aplicações com C#