Título de eleitor

Valida um título de eleitor. Um título tem no máximo 12 dígitos, então um valor de 13 dígitos é rejeitado.

• Um título é um número sequencial de 8 dígitos, um código de unidade federativa de 2 dígitos (01 a 28) e 2 dígitos verificadores.
• O TSE despreza os zeros à esquerda do número sequencial na emissão, então um valor mais curto é lido como o título sem eles e completado com zeros à esquerda até 12 dígitos antes da validação (123450159 é validado como 000123450159). É preciso ao menos um dígito sequencial: o menor valor aceito tem 5 dígitos.
• Espaços, pontos, hífens e barras são aceitos ao redor e entre os grupos. Qualquer outro caractere invalida o valor.
• A Resolução TSE nº 23.659/2021, art. 36, que revogou a Resolução TSE nº 21.538/2003 (art. 140), fixa o layout, a tabela das unidades federativas e dois dígitos verificadores "determinados com base no 'Módulo 11'". Ela não traz pesos nem regra por estado: os pesos e a regra que troca o resto 0 por 1 para São Paulo (01) e Minas Gerais (02) não têm fonte oficial e seguem as referências da comunidade abaixo.

import { generateVoterId, isValidVoterId } from '@brazilian-utils/brazilian-utils';

const voterId = generateVoterId('SP');

isValidVoterId(voterId); // true
isValidVoterId('102385010671'); // true (12 dígitos)
isValidVoterId('123450159'); // true (000123450159 emitido sem os zeros à esquerda)
isValidVoterId('1234567880191'); // false (13 dígitos, mais que os 12 que o TSE permite)
isValidVoterId('123456780124'); // false (dígitos verificadores inválidos)

Fonte: Resolução TSE nº 23.659/2021, art. 36 ("composto por até 12 algarismos", "os oito primeiros algarismos serão sequenciados, desprezando-se, na emissão, os zeros à esquerda"), brutils e siga0984.

Formata um título de eleitor com o agrupamento de 12 dígitos 0000 0000 00 00.

• Opções (FormatVoterIdOptions): pad completa o valor com zeros à esquerda até 12 dígitos, restaurando os zeros de um título emitido sem eles; obfuscate esconde os 3 primeiros dígitos e os 2 dígitos verificadores, deixando visível o código da unidade federativa. A máscara esconde por posição, então use pad junto com obfuscate para um título passado como número, que perdeu os zeros à esquerda: sem ele a máscara cai sobre os dígitos verificadores. Um valor vazio, ou sem dígitos, devolve '' mesmo com pad.
• Sem pad, um valor mais curto é formatado a partir da esquerda, como um título digitado pela metade.
• Os dígitos além do 12º são descartados.
• Nenhuma autoridade publica uma regra de mascaramento para o título de eleitor, então o obfuscate usa a que as Leis de Diretrizes Orçamentárias definem para a divulgação do CPF ("ocultar os três primeiros dígitos e os dois dígitos verificadores", Lei nº 14.194/2021, art. 149, regra criada pela Lei nº 12.309/2010, art. 87, § 5º), um número com a mesma estrutura.

import { formatVoterId } from '@brazilian-utils/brazilian-utils';

formatVoterId('123456780175'); // '1234 5678 01 75'
formatVoterId('123456780175', { obfuscate: true }); // '***4 5678 01 **'
formatVoterId('123450159', { pad: true }); // '0001 2345 01 59'
formatVoterId('123450159'); // '1234 5015 9' (lido como um título digitado pela metade)

Remove a formatação do título de eleitor, mantém apenas os dígitos e limita o resultado a 12 dígitos. Um valor mais curto é mantido como está, sem acrescentar zeros à esquerda.

import { parseVoterId } from '@brazilian-utils/brazilian-utils';

parseVoterId('1234 5678 01 75'); // '123456780175'
parseVoterId('12345 01 59'); // '123450159'

Gera um título de eleitor válido aleatório. O argumento opcional state (StateCode, ou "ZZ" para um título expedido no exterior) define o código de unidade federativa.

• state ignora maiúsculas/minúsculas e espaços nas pontas ('sp' é 'SP'). Uma UF desconhecida, ou um valor que não seja string, usa "ZZ" (UF 28).
• O resultado sempre tem 12 dígitos, com os zeros à esquerda do número sequencial; o mesmo título sem eles também é válido.

import { generateVoterId } from '@brazilian-utils/brazilian-utils';

generateVoterId(); // título de eleitor aleatório válido (exterior, "ZZ")
generateVoterId('SP'); // título de eleitor aleatório válido de São Paulo
generateVoterId('XX'); // usa "ZZ" em vez de lançar erro

Fonte: Lei nº 14.194/2021, art. 149, a regra de mascaramento do CPF que o obfuscate toma emprestada, criada pela Lei nº 12.309/2010, art. 87, § 5º e repetida pelas LDOs seguintes (a de 2026, Lei nº 15.321/2025, art. 163, a repete).

Lê os campos de um título de eleitor, como um VoterIdInfo, ou null quando o isValidVoterId retornaria false.

• Campos: sequentialNumber (8 dígitos), federativeUnion (o código '01' a '28'), stateCode (um StateCode, ou null para '28', os eleitores no exterior) e checkDigits (2 dígitos). Os códigos são strings que mantêm os zeros à esquerda.
• Um título expedido sem os zeros à esquerda do número sequencial é lido como o isValidVoterId o lê, preenchido com zeros à esquerda até 12 dígitos: '123450159' dá o sequentialNumber '00012345'.
• O stateCode é a unidade federativa da inscrição, não necessariamente onde o eleitor mora hoje.

import { getVoterIdInfo } from '@brazilian-utils/brazilian-utils';

getVoterIdInfo('1023 8501 06 71');
// {
//   sequentialNumber: '10238501',
//   federativeUnion: '06',
//   stateCode: 'PR',
//   checkDigits: '71',
// }

getVoterIdInfo('000000002801'); // { sequentialNumber: '00000000', federativeUnion: '28', stateCode: null, checkDigits: '01' }
getVoterIdInfo('123456780124'); // null (dígitos verificadores inválidos)

Fonte: Resolução TSE nº 23.659/2021, art. 36.