Validação de CPF e CNPJ

Antes de chamar a API da Raims com tax_id, sua integração deve validar o formato e os dígitos verificadores do CPF ou CNPJ no próprio sistema.

Faça essa verificação enquanto seu cliente informa o documento, para indicar no próprio campo o que precisa ser corrigido. Isso evita requisições com tax_id inválido e erros de validação na aplicação que consome nossa API, oferecendo uma experiência melhor aos seus clientes finais.

O campo tax_id aceita CPF, CNPJ numérico e CNPJ alfanumérico. A validação confere o formato e os dois dígitos verificadores, que são calculados a partir dos caracteres anteriores.

Nas respostas da API, tax_id_type identifica o documento retornado em tax_id: cpf para CPF e cnpj para CNPJ, numérico ou alfanumérico.

Antes de enviar tax_id

Complete estas etapas no seu sistema antes de enviar a requisição aos servidores da Raims:

A validação feita no formulário não substitui a validação no backend da integração.

Use uma mensagem como "Confira o CPF ou CNPJ informado". Preserve o valor digitado para que seu cliente possa corrigir. A integração deve enviar o documento informado pelo cliente, sem substituir os dígitos verificadores por outros que façam o cálculo passar.

Exemplo em JavaScript

O código em JavaScript serve como referência para implementar a validação na linguagem da sua integração. Aplique as mesmas regras no backend e, quando houver formulário, também na interface para orientar o preenchimento.

Neste exemplo, a função retorna o documento normalizado quando ele é válido, ou null quando precisa de correção. Ela aceita CPF, CNPJ numérico e CNPJ alfanumérico.

function normalizeAndValidateTaxId(value) {
  if (typeof value !== 'string') return null;

  const input = value.replace(/[\p{White_Space}./-]/gu, '');
  if (!/^[0-9A-Za-z]+$/.test(input)) return null;

  const taxId = input.toUpperCase();
  const isCpf = /^[0-9]{11}$/.test(taxId);
  const isCnpj = /^[0-9A-Z]{12}[0-9]{2}$/.test(taxId);
  if (!isCpf && !isCnpj) return null;
  if (isCpf && /^([0-9])\1{10}$/.test(taxId)) return null;

  const base = taxId.slice(0, -2);
  if (isCnpj && base === '000000000000') return null;

  const weights = isCpf
    ? [11, 10, 9, 8, 7, 6, 5, 4, 3, 2]
    : [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
  const first = calculateCheckDigit(base, weights.slice(1));
  const second = calculateCheckDigit(`${base}${first}`, weights);

  return taxId.endsWith(`${first}${second}`) ? taxId : null;
}

function calculateCheckDigit(base, weights) {
  const sum = [...base].reduce(
    (total, character, index) =>
      total + (character.charCodeAt(0) - 48) * weights[index],
    0,
  );
  const remainder = sum % 11;
  return remainder < 2 ? 0 : 11 - remainder;
}

// Documento ilustrativo usado no manual de cálculo da Receita Federal.
const taxId = normalizeAndValidateTaxId('12.abc.345/01de-35');
if (taxId === null) {
  throw new Error('Confira o CPF ou CNPJ informado');
}

const body = { tax_id: taxId }; // { tax_id: '12ABC34501DE35' }
// Acrescente os demais campos exigidos pelo endpoint antes de enviar.

Para um CPF como 123.456.789-09, a função retorna 12345678909. Entradas como 00000000000, 12ABC34501DE34 ou um valor recebido como número retornam null. Trate esse resultado no formulário ou no fluxo do seu backend antes de montar a requisição.

Normalize o documento

Remova espaços, pontos (.), barras (/) e hífens (-) e converta letras para maiúsculas. A Raims aceita essa formatação e aplica a normalização antes de conferir o documento.

Mantenha o documento como texto em todas as etapas. Converter para número remove zeros à esquerda; extrair somente números apaga as letras de um CNPJ alfanumérico. Caracteres fora dos conjuntos permitidos devem causar uma mensagem de validação, em vez de serem apagados silenciosamente.

Os CNPJs numéricos continuam válidos e coexistem com o formato alfanumérico. Prepare campos, máscaras e bibliotecas para ambos, conforme as perguntas e respostas da Receita Federal sobre o CNPJ alfanumérico.

Como validar um CPF

Após a normalização, um CPF deve ter exatamente 11 caracteres, todos de 0 a 9. A Raims recusa sequências com o mesmo dígito repetido, como 00000000000 e 11111111111.

Os nove primeiros dígitos formam a base; os dois últimos são verificadores. Calcule cada verificador com o módulo 11:

1. Multiplique os nove dígitos da base, da esquerda para a direita, pelos pesos 10, 9, 8, 7, 6, 5, 4, 3, 2 e some os produtos.
2. Obtenha o resto da divisão da soma por 11. Se for 0 ou 1, o verificador é 0; caso contrário, é 11 - resto.
3. Acrescente o primeiro verificador calculado à base. Repita usando os pesos 11, 10, 9, 8, 7, 6, 5, 4, 3, 2 para obter o segundo.
4. Compare os dois resultados com os dois últimos dígitos recebidos.

A rotina está documentada no Protocolo de Arrecadação da GRU, seção IV, do Tesouro Nacional.

No exemplo ilustrativo 12345678909, a primeira soma é 210, com resto 1, resultando em 0. A segunda soma é 255, com resto 2, resultando em 9. Os verificadores calculados coincidem com 09.

Como validar um CNPJ

Após a normalização, confira estas condições:

A Raims também recusa CNPJ com os 12 caracteres da base iguais a zero, incluindo 00000000000000. O cálculo é o mesmo para CNPJ numérico e alfanumérico:

1. Converta cada caractere da base para código ASCII - 48. Números mantêm seu valor; A vale 17, B vale 18 e Z vale 42.
2. Multiplique os 12 valores pelos pesos 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2 e some os produtos.
3. Divida a soma por 11. Resto 0 ou 1 produz verificador 0; nos demais casos, use 11 - resto.
4. Acrescente o primeiro verificador e repita com os pesos 6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2.
5. Compare os dois verificadores calculados com os recebidos.

O manual de cálculo dos dígitos verificadores publicado pela Receita Federal usa 12ABC34501DE35: as somas 459 e 424 resultam nos verificadores 3 e 5. Esse é um exemplo de cálculo, sem identificação de um cliente Raims.

Como tratar INVALID_TAXID

Quando a API retornar HTTP 400, com error.code igual a INVALID_FIELDS, procure em error.details o item com field: "tax_id" e code: "INVALID_TAXID".

Esse detalhe indica que o valor informado não passou na validação de CPF ou CNPJ. Confira o tamanho após a normalização, os caracteres permitidos e os dois verificadores. Um CPF com todos os dígitos iguais ou um CNPJ com os 12 caracteres da base iguais a zero também é recusado.

Associe o erro ao campo CPF/CNPJ na interface do seu sistema e mantenha os demais dados preenchidos. Peça a correção antes de tentar novamente; reenviar o mesmo valor inválido não resolve o problema. A API continua validando o documento em todas as requisições, mesmo que sua aplicação já o tenha conferido.

Consulte a referência do endpoint para os campos e requisitos da requisição e Códigos HTTP das respostas para o formato geral dos erros.

O que essa validação confirma

Passar no cálculo confirma somente que o formato e os dígitos verificadores estão consistentes. Isso não comprova existência do cadastro, situação cadastral regular ou titularidade. Os exemplos deste guia servem para entender o cálculo; não os use como documentos de clientes reais.

Quando seu fluxo exigir comprovação cadastral ou de identidade, faça a verificação correspondente. Consulte os serviços oficiais da Receita Federal para situação cadastral do CPF e consulta de CNPJ.