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

> Aprenda a integrar validação de CPF em projetos Unity usando C# e UnityWebRequest para consumir a API da CPFHub.io.

**Publicado:** 12/07/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-unity-para-aplicacoes-com-csharp

---

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](https://docs.unity3d.com/Manual/UnityWebRequest.html) 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**](https://www.cpfhub.io/)

---

## 2. Crie as classes de dados

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

```csharp
// 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:

```csharp
// 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:

```csharp
// 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:

```csharp
// 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:

1. Crie um Canvas com os elementos de UI (InputField, Button, Text, Panels).
2. Adicione um GameObject vazio e anexe o script `CpfHubService`.
3. Adicione o script `CpfConsultaUI` a outro GameObject e conecte as referências no Inspector.
4. 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.

### 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)
- [Como consumir API de CPF em C# com HttpClient e .NET 8](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-csharp-com-httpclient-e-dotnet-8)
- [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)

---

## Conclusão

Integrar a API da [**CPFHub.io**](https://www.cpfhub.io/)

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