Como Validar um Número de CUIT com uma API

Se você está desenvolvendo um produto que atende usuários ou empresas argentinas, vai inevitavelmente encontrar o CUIT. Seja processando faturas, realizando onboarding de empresas ou integrando com a AFIP (autoridade fiscal da Argentina), validar um CUIT é uma das primeiras coisas que seu backend precisa fazer de forma confiável. Um CUIT malformado pode causar falhas em declarações fiscais, pagamentos rejeitados e problemas de compliance. Neste guia, vamos percorrer o que é um CUIT, como funciona sua estrutura, o algoritmo do dígito verificador, as armadilhas comuns que os desenvolvedores enfrentam, e como validar CUITs programaticamente usando a API Validate da Normadata.

O que é um CUIT?

O CUIT (Clave Unica de Identificacion Tributaria) é o número de identificação fiscal único da Argentina. Ele é emitido pela AFIP e atribuído a cada pessoa física, empresa e entidade jurídica que participa do sistema tributário do país. Pense nele como o equivalente argentino ao EIN nos Estados Unidos ou ao RFC no México. Toda empresa registrada na Argentina tem um CUIT, e as pessoas que trabalham formalmente também recebem um. Você o verá em faturas, comprovantes fiscais, documentos de folha de pagamento e registros de contas bancárias. Ao contrário do DNI (número de identidade nacional), o CUIT inclui um prefixo de tipo e um dígito verificador, o que permite validá-lo algoritmicamente sem precisar consultar um banco de dados externo.

Estrutura e formato do CUIT

Um CUIT é um número de 11 dígitos escrito no formato XX-XXXXXXXX-X, dividido em três partes: um prefixo de tipo com dois dígitos, um corpo de oito dígitos (geralmente o número do DNI da pessoa) e um único dígito verificador. O prefixo de tipo indica o tipo de entidade:

• 20 — Pessoa física masculina
• 23 — Pessoa física masculina (alternativo, usado quando 20 gera um dígito verificador inválido)
• 24 — Pessoa física masculina (segundo alternativo)
• 27 — Pessoa física feminina
• 30 — Empresa ou entidade jurídica
• 33 — Entidade jurídica (alternativo)
• 34 — Entidade jurídica (segundo alternativo)

Por exemplo, um CUIT como 20-12345678-5 indica que pertence a uma pessoa física masculina (prefixo 20), com DNI 12345678 e dígito verificador 5. O corpo de oito dígitos é tipicamente o número do DNI da pessoa para pessoas físicas, ou um número sequencial atribuído pela AFIP para empresas. O número completo sempre tem 11 dígitos sem separadores quando transmitido eletronicamente, embora seja comumente exibido com hífens para facilitar a leitura.

O algoritmo do dígito verificador

O último dígito de um CUIT é um dígito verificador calculado usando um algoritmo de módulo 11 com pesos fixos. Isso permite detectar erros de digitação e transcrição sem precisar consultar nenhum serviço externo. Veja como o algoritmo funciona:

1. Escreva os primeiros 10 dígitos do CUIT.
2. Atribua os seguintes pesos a cada posição: 5, 4, 3, 2, 7, 6, 5, 4, 3, 2.
3. Multiplique cada dígito pelo seu peso correspondente.
4. Some todos os produtos.
5. Calcule o resto: soma módulo 11.
6. Subtraia o resto de 11 para obter o dígito verificador.
7. Se o resultado for 11, o dígito verificador é 0. Se o resultado for 10, o dígito verificador é 9 (ou o CUIT é inválido dependendo do prefixo usado).

Por exemplo, dados os primeiros 10 dígitos 20-29883741, você multiplica cada dígito pelo seu peso (2x5, 0x4, 2x3, 9x2, 8x7, 8x6, 3x5, 7x4, 4x3, 1x2), soma os produtos (10+0+6+18+56+48+15+28+12+2 = 195), calcula 195 mod 11 = 8, e então 11-8 = 3. O CUIT completo seria 20-31456789-4. Se o dígito verificador calculado não corresponder ao 11º dígito fornecido, o CUIT é inválido.

Armadilhas comuns na validação

Ao validar CUITs em produção, os desenvolvedores frequentemente encontram vários problemas que podem causar rejeições falsas ou bugs silenciosos:

• Zeros à esquerda no corpo do DNI — Alguns números de DNI têm menos de 8 dígitos e precisam de padding com zeros. Se o seu parser remover os zeros à esquerda, o cálculo do dígito verificador vai falhar.
• Tratamento de hífens — CUITs são armazenados com e sem hífens em diferentes sistemas. Normalize sempre removendo hífens e espaços antes da validação.
• Suposições sobre o prefixo de tipo — Não assuma que o prefixo 20 é sempre masculino ou 30 é sempre empresa. Prefixos alternativos (23, 24, 33, 34) existem especificamente para casos onde o prefixo primário gera um dígito verificador inválido.
• Tipos string vs. número — Sempre trate CUITs como strings, nunca como inteiros. Converter para número vai eliminar zeros à esquerda e produzir resultados incorretos.
• Confundir CUIT com CUIL — O CUIL (Clave Unica de Identificacion Laboral) usa o mesmo formato e algoritmo. Funcionalmente são intercambiáveis para fins de validação, mas servem a propósitos diferentes nos sistemas governamentais.

Validando com a API da Normadata

Em vez de implementar o algoritmo do dígito verificador você mesmo e manter a lógica de casos extremos, é possível validar CUITs com uma única chamada de API ao endpoint Validate da Normadata. A API normaliza a entrada, verifica o formato e o checksum, e retorna metadados estruturados incluindo o tipo de entidade e o valor formatado. Veja exemplos em diferentes linguagens:

curl -X POST https://api.normadata.io/v1/validate/tax-ids \
 -H "X-API-Key: nd_your_key_here" \
 -H "Content-Type: application/json" \
 -d {
 "value": "20-31456789-4",
 "country": "AR",
 "type": "cuit"
 }

import requests

response = requests.post(
 "https://api.normadata.io/v1/validate/tax-ids",
 headers={"X-API-Key": "nd_your_key_here"},
 json={
 "value": "20-31456789-4",
 "country": "AR",
 "type": "cuit"
 }
)
data = response.json()
print(data["valid"]) # True

const response = await fetch("https://api.normadata.io/v1/validate/tax-ids", {
 method: "POST",
 headers: {
 "X-API-Key": "nd_your_key_here",
 "Content-Type": "application/json"
 },
 body: JSON.stringify({
 value: "20-31456789-4",
 country: "AR",
 type: "cuit"
 })
});
const data = await response.json();
console.log(data.valid); // true

{
 "valid": true,
 "country": "AR",
 "type": "cuit",
 "value": {
 "raw": "20298837413",
 "formatted": "20-31456789-4"
 },
 "metadata": {
 "prefix": "20",
 "entity_type": "persona_fisica_masculino",
 "dni": "29883741",
 "check_digit": "3"
 }
}

{
 "valid": false,
 "country": "AR",
 "type": "cuit",
 "value": {
 "raw": "20298837419",
 "formatted": "20-29883741-9"
 },
 "error": {
 "code": "err_validation_failed",
 "message": "Check digit mismatch. Expected 3, received 9."
 }
}

Próximos passos

Agora que você entende como funciona a validação de CUIT, pode integrá-la ao seu fluxo de onboarding, sistema de faturamento ou pipeline de compliance. A API Validate da Normadata lida não apenas com CUITs, mas também com CBUs (números de conta bancária), DNIs e outros identificadores argentinos — mais IDs fiscais de 8 outros países sul-americanos usando a mesma API consistente. Consulte a página de cobertura para a lista completa de identificadores suportados, ou acesse a documentação da API para começar a fazer requisições.