Telefone

Validar

• JavaScript, biblioteca
• Python, biblioteca
• Go, biblioteca1 caso falha
• Ruby, biblioteca21 casos falham
• Rust, biblioteca
• .NET, biblioteca9 casos falham
• Erlang, biblioteca39 casos falham

Valida um número de telefone brasileiro, celular ou fixo por padrão.

• A função aceita um código de país (+55, 0055 ou só 55) e o remove primeiro, como em phone.parse. Um 55 sem + nem 00 só é removido quando restam 10 ou 11 dígitos.
• O DDD precisa ser um código de área brasileiro válido (00 não é).
• Qualquer caractere que não seja dígito, espaço em branco ou ()+.-/ (uma letra, por exemplo) torna o valor inválido. Até a 2.4.0 esses caracteres eram descartados, então 11 98765-4321x era válido.
• A verificação de caracteres vale para a forma em string de qualquer entrada, não só para strings: um objeto cujo toString retorna "190x" é inválido, como "190x" é, enquanto um que retorna "190" é lido como o número de serviço 190 com accept: ["service"]. Uma lista de caracteres não é lida como a string juntada e é inválida. Só phone.isValid lê a forma em string; phone.isValidMobile, phone.isValidLandline e phone.isValidService retornam false para um valor que não é string.
• options.accept (padrão ["mobile", "landline"]) lista os tipos de número que valem como válidos: mobile, landline e service (os números que phone.isValidService reconhece). Uma lista vazia rejeita tudo.
• options.version (1 ou 2, padrão 1) é repassada a phone.isValidMobile: as duas versões exigem 7, 8 ou 9 como primeiro dígito do assinante, e a 2 também rejeita a série 700 (serviço por satélite).
• Um celular precisa de 7, 8 ou 9 como primeiro dígito do assinante nas duas regras de numeração (Resolução Anatel nº 749/2022, art. 12). A 2.4.0 também aceitava 6 por padrão.

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

isValidPhone('11900000000'); // true
isValidPhone('11712345678', { version: 2 }); // true (7, 8 e 9 são todos SMP)
isValidPhone('11700123456', { version: 2 }); // false (a série 700 é de satélite)
isValidPhone('11612345678'); // false (6 não é SMP)
isValidPhone('+55 11 98765-4321'); // true (código de país aceito)
isValidPhone('08001234567'); // false (números de serviço não são aceitos por padrão)
isValidPhone('08001234567', { accept: ['service'] }); // true
isValidPhone('11900000000', { accept: [] }); // false

Formatar

• JavaScript, biblioteca
• Python, biblioteca15 casos falham
• Go, biblioteca3 casos falham
• Ruby, biblioteca100 casos falham
• Rust, biblioteca2 casos falham
• .NET, biblioteca2 casos falham
• Erlang, biblioteca15 casos falham

Formata um número de telefone de acordo com os padrões brasileiros.

• options.mask (padrão sn) escolhe o padrão: sn (só o número do assinante, 9 dígitos: 98765-4321), nanp (DDD mais número, (11) 90000-0000, 11 dígitos para celular e 10 para fixo, qualquer outro tamanho mantém o agrupamento de 11 dígitos), e164 (+5511987654321), international (+55 11 98765-4321), service (0800 123 4567, 4004-1234) e auto. Uma mask desconhecida usa sn.
• Se o valor incluir DDD, passe { mask: "auto" } ou "nanp": a máscara padrão sn presume que não há DDD e o corta (11900000000 dá 11900-0000).
• auto escolhe service para um número de serviço, international quando o valor traz código de país e, nos outros casos, nanp para mais de 9 dígitos e sn para o resto.
• e164 e international primeiro removem um código de país da entrada, como phone.parse faz, e usam service para um número de serviço. e164 mantém no máximo os 11 dígitos nacionais, como international (119888877660000 dá +5511988887766). Até a 2.4.0 e164 mantinha todos.
• sn e nanp também removem um +55 ou 0055 explícito, então +5511987654321 dá (11) 98765-4321 em nanp. Até a 2.4.0 dava (55) 11987-6543. Um 55 sem + nem 00 fica, pois pode ser o DDD (5511988887777 dá (55) 11988-8877 em nanp).
• Um número ainda sendo digitado depois de um código de país explícito é formatado até onde vai (+55 11 9 dá +55 11 9 em international e auto, +55119 em e164). O valor +55 sozinho retorna uma string vazia.
• options.obfuscate (padrão false, lido como verdadeiro ou falso) oculta o número do assinante com * em todas as máscaras. Mantém o prefixo que identifica uma região ou um serviço (o DDD, +55, um código como 0800, a raiz 300X/400X) e os 2 últimos dígitos que a máscara comporta: (11) *****-**21, 0800 *** **67, 4004-**34. É uma convenção da biblioteca, não uma regra oficial. Segue a contagem da conta gov.br, que mostra só os 2 últimos dígitos do celular. O DDD continua visível, embora o gov.br o esconda.
• Com a máscara padrão de número do assinante, um valor com DDD é cortado antes de ser ocultado, então o par visível não são os 2 últimos dígitos da entrada (11987654321 dá *****-**43). Passe { mask: "auto" } quando o valor tiver DDD.
• Na máscara service com obfuscate, um valor que é só um prefixo de serviço até agora o mantém (0800 fica 0800), pois o prefixo nomeia um serviço, não um assinante. Um valor curto demais para ser reconhecido (080) é totalmente oculto (***). Um valor que não é número de serviço vira um * por dígito, o que esconde os dígitos mas não quantos eram.
• Com obfuscate, um código de utilidade pública de 3 dígitos válido (190) é retornado como está nas máscaras service, auto, e164 e international. As máscaras sn e nanp o leem como um número curto comum e o ocultam.
• Em e164 com obfuscate, os dígitos depois do 11º dígito nacional são descartados. Isso só afeta entrada inválida.
• Um número só é lido se for um inteiro seguro não negativo. Número negativo, fracionário, não finito ou inseguro retorna uma string vazia (a 2.4.0 lia os dígitos de qualquer número).

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

formatPhone('987654321'); // 98765-4321 (padrão "sn", sem DDD)
formatPhone('11900000000', { mask: 'nanp' }); // (11) 90000-0000
formatPhone('11900000000', { mask: 'auto' }); // (11) 90000-0000
formatPhone('1130000000', { mask: 'nanp' }); // (11) 3000-0000 (fixo de 10 dígitos)
formatPhone('1130000000', { mask: 'auto' }); // (11) 3000-0000 (fixo de 10 dígitos)
formatPhone('11987654321', { mask: 'e164' }); // +5511987654321
formatPhone('+5511987654321', { mask: 'international' }); // +55 11 98765-4321
formatPhone('+55 11 9', { mask: 'auto' }); // +55 11 9 (digitado após o +55, o 55 não é lido como DDD)
formatPhone('+5511987654321', { mask: 'nanp' }); // (11) 98765-4321
formatPhone('08001234567', { mask: 'service' }); // 0800 123 4567
formatPhone('40041234', { mask: 'service' }); // 4004-1234
formatPhone('+5511987654321', { mask: 'auto' }); // +55 11 98765-4321 ("auto" detecta o prefixo +55 e escolhe "international")
formatPhone('5508001234567', { mask: 'auto' }); // 0800 123 4567 ("auto" lê o número 0800, não um +55 08)
formatPhone('987654321', { obfuscate: true }); // *****-**21
formatPhone('11987654321', { mask: 'auto', obfuscate: true }); // (11) *****-**21
formatPhone('1130000000', { mask: 'auto', obfuscate: true }); // (11) ****-**00
formatPhone('+5511987654321', { mask: 'auto', obfuscate: true }); // +55 11 *****-**21
formatPhone('11987654321', { mask: 'e164', obfuscate: true }); // +5511*******21
formatPhone('08001234567', { mask: 'service', obfuscate: true }); // 0800 *** **67
formatPhone('40041234', { mask: 'service', obfuscate: true }); // 4004-**34
formatPhone('11988887766', { mask: 'service', obfuscate: true }); // *********** (não é número de serviço)
formatPhone('11987654321', { obfuscate: true }); // *****-**43 (CUIDADO: a "sn" trunca antes, então "43", e não "21")
formatPhone('11900000000'); // 11900-0000 (CUIDADO: a máscara padrão "sn" trunca um número com DDD)

Interpretar

• JavaScript, biblioteca
• Python, biblioteca
• Go, biblioteca4 casos falham
• Ruby, biblioteca5 casos falham
• Rust, biblioteca4 casos falham
• .NET, biblioteca4 casos falham
• Erlang, biblioteca

Remove a formatação do telefone e mantém só os dígitos, limitados a 11.

• Um código de país explícito, escrito como +55 ou 0055 no início do valor, é sempre removido, quantos dígitos vierem depois, então um número ainda sendo digitado mantém o DDD: +55 11 9 dá 119. Até a 2.4.0 a regra de tamanho abaixo valia também para as formas explícitas, então +55 11 9 dava 55119.
• Um 55 inicial sem + nem 00 é removido apenas quando restam 10 ou 11 dígitos (DDD mais um assinante de 8 ou 9 dígitos). Assim, o DDD 55 não é confundido com o código de país: 55987654321 é mantido, e 55 11 9 dá 55119.
• Um número só é lido se for um inteiro seguro não negativo. Número negativo, fracionário, não finito ou inseguro retorna uma string vazia (a 2.4.0 lia os dígitos de qualquer número).

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

parsePhone('(11) 90000-0000'); // 11900000000
parsePhone('+55 (11) 98765-4321'); // 11987654321
parsePhone('5511987654321'); // 11987654321
parsePhone('+55 11 9'); // 119 (código de país explícito, número ainda curto)
parsePhone('55987654321'); // 55987654321 (DDD 55, não confundido com o código de país +55)

Gerar

• JavaScript, biblioteca
• Python, biblioteca1 caso falha
• Go, biblioteca4 casos falham
• Ruby, biblioteca2 casos falham
• Rust, biblioteca3 casos falham
• .NET, biblioteca1 caso falha
• Erlang, biblioteca3 casos falham

Gera um número de telefone brasileiro aleatório, sem máscara.

Use phone.format para formatá-lo.

• type: mobile (DDD + 9 dígitos começando com 9, válido nas duas versões de numeração de phone.isValidMobile), landline (DDD + 8 dígitos começando com 2 a 5) ou service (sem DDD: um Código Não Geográfico como 0800 + 7 dígitos, ou um número abreviado 300X/400X). Sem type, a função escolhe um celular ou um fixo ao acaso, nunca um número de serviço.
• Um fixo nunca começa com 6 depois do DDD: a faixa de 2 a 5 continua válida depois que a Resolução Anatel nº 777/2025 a estreita, em 1º de março de 2027. Até a 2.4.0 um 6 podia ser sorteado.
• phone.isValid aceita o resultado de celular ou fixo, e phone.isValidService o de serviço.
• Usa Math.random(), então o resultado não é criptograficamente seguro: não use para fins de segurança.

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

generatePhone(); // '11912345678' ou '1131234567'
generatePhone('mobile'); // '11912345678'
generatePhone('landline'); // '1131234567'
generatePhone('service'); // '08001234567' ou '40041234'

Is valid landline

• JavaScript, biblioteca
• Python, biblioteca
• Go, biblioteca
• Ruby, biblioteca4 casos falham
• Rust, biblioteca2 casos falham
• .NET, biblioteca4 casos falham
• Erlang, biblioteca

Valida um número fixo: DDD mais 8 dígitos começando com 2 a 6.

• A função aceita um código de país (+55, 0055 ou só 55) e o remove primeiro, como em phone.parse.
• O DDD precisa ser um código de área brasileiro válido (00 não é).
• Qualquer caractere que não seja dígito, espaço em branco ou ()+.-/ (uma letra, por exemplo) torna o valor inválido. Até a 2.4.0 esses caracteres eram descartados, então 11 3000-0000x era válido.
• O primeiro dígito do número é de 2 a 6, a faixa do STFC e do SCM da Resolução Anatel nº 749/2022, art. 11, I, "a".
• Mudança prevista, ainda não aplicada: a partir de 1º de março de 2027 a Resolução Anatel nº 777/2025, art. 21, deixa só 2 a 5 para o STFC e move o SCM para números de 9 dígitos começando com 6. A partir dessa data um fixo começando com 6 terá de ser rejeitado.

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

isValidLandlinePhone('1130000000'); // true
isValidLandlinePhone('+55 11 3000-0000'); // true (código de país aceito)

Is valid mobile

• JavaScript, biblioteca
• Python, biblioteca
• Go, biblioteca1 caso falha
• Ruby, biblioteca9 casos falham
• Rust, biblioteca3 casos falham
• .NET, biblioteca3 casos falham
• Erlang, biblioteca

Valida um número de celular: DDD mais 9 dígitos.

• A função aceita um código de país (+55, 0055 ou só 55) e o remove primeiro, como em phone.parse. Um 55 sem + nem 00 só é removido quando restam 10 ou 11 dígitos.
• O DDD precisa ser um código de área brasileiro válido (00 não é).
• Qualquer caractere que não seja dígito, espaço em branco ou ()+.-/ (uma letra, por exemplo) torna o valor inválido. Até a 2.4.0 esses caracteres eram descartados, então 11 98765-4321x era válido.
• O primeiro dígito do assinante precisa ser 7, 8 ou 9 nas duas regras de numeração (Resolução Anatel nº 749/2022, art. 12, I, "a": Serviço Móvel Pessoal). A 2.4.0 também aceitava 6 na versão 1, embora 6 não seja SMP.
• options.version (1 ou 2, padrão 1) escolhe a regra de numeração para a série 700. A versão 1 a aceita. A versão 2 a rejeita, porque o art. 12, II, "a" a destina ao serviço por satélite.
• A Resolução Anatel nº 777/2025 reescreve o art. 12 a partir de 1º de março de 2027 (só 8 e 9 para SMP, mais a série 700 como SMP por satélite). Ela ainda não está em vigor, então a função não a aplica.

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

isValidMobilePhone('11900000000'); // true
isValidMobilePhone('11712345678', { version: 1 }); // true
isValidMobilePhone('11712345678', { version: 2 }); // true (7 também é SMP)
isValidMobilePhone('11612345678'); // false (6 não é SMP, em nenhuma das versões)
isValidMobilePhone('11700123456'); // true (a versão 1 mantém a série 700)
isValidMobilePhone('11700123456', { version: 2 }); // false (a série 700 é de satélite)

Is valid service

• JavaScript, biblioteca
• Python, biblioteca
• Go, biblioteca4 casos falham
• Ruby, biblioteca10 casos falham
• Rust, biblioteca12 casos falham
• .NET, biblioteca10 casos falham
• Erlang, biblioteca

Valida um número de serviço brasileiro, discado sem DDD. A função verifica só a estrutura: o número não precisa estar atribuído a ninguém.

• Um código de país (+55, 0055 ou só 55) é aceito e removido primeiro, como em phone.isValid com accept: ["service"]: +55 0800 123 4567 é válido. Até a 2.4.0 era rejeitado. Um 55 sem + nem 00 só é removido quando sobram 11 dígitos que formam um número de serviço (5508001234567 é válido; 55190 e 5540041234 não são).
• Qualquer caractere que não seja dígito, espaço em branco ou ()+.-/ (uma letra, por exemplo) torna o valor inválido. Até a 2.4.0 esses caracteres eram descartados, então abc190 era válido.
• Códigos Não Geográficos 0300, 0303, 0500, 0800 e 0900 seguidos de 7 dígitos (11 no total; a forma antiga de 6 dígitos, como 0800 123456, é rejeitada). A regra do 0500 que codifica um valor de doação nos dois últimos dígitos não é aplicada.
• Os números abreviados 300X/400X (8 dígitos). Outros prefixos de operadora são rejeitados.
• Os códigos de utilidade pública de 3 dígitos designados pela Anatel (por exemplo 190 e 192), da lista SUP atual da Anatel e do Anexo do Ato nº 43.151/2004. 112 é aceito: a lista SUP atual o traz (a 2.4.0 o rejeitava).
• 911 continua rejeitado. A lista SUP o cita ao lado do 112, mas a Resolução Anatel nº 749/2022, art. 13, destina aos serviços de utilidade pública só a faixa 1N₂N₁. Os dois textos oficiais conflitam, então a resposta da 2.4.0 é mantida.

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

isValidServicePhone('0800 123 4567'); // true
isValidServicePhone('4004-1234'); // true
isValidServicePhone('190'); // true
isValidServicePhone('+55 0800 123 4567'); // true (código de país aceito)
isValidServicePhone('11987654321'); // false (número geográfico)

Remove international dialing code

• JavaScript, biblioteca
• Python, biblioteca
• Go, biblioteca
• Ruby, biblioteca
• Rust, biblioteca
• .NET, biblioteca
• Erlang, biblioteca

Remove um +55 ou 55 do início.