Como consultar CNPJ via API no Swift.

Q: Como lidar com campos que podem vir nulos?

Declare as propriedades como opcionais (String?). Vários campos da resposta podem ser null quando a fonte não tem a informação.

Aprenda a consultar CNPJ via API no Swift com URLSession: código pronto, leitura do JSON, tratamento de erros e boas práticas. API de CNPJ grátis, sem chave e sem cadastro.

Por que usar a API do openCNPJ no Swift

Em apps iOS e macOS, a consulta de CNPJ com URLSession e Codable transforma o JSON da API em structs tipadas. A estratégia convertFromSnakeCase converte razao_social em razaoSocial automaticamente.

Grátis, sem chave de acesso e sem cadastro.
Resposta em JSON com razão social, situação cadastral, endereço, CNAEs, sócios e Simples Nacional.
Aceita o CNPJ numérico e o novo CNPJ alfanumérico.
Limite de 10 requisições por segundo por IP.

O que você precisa

Swift 5.7+ com async/await (iOS 15+, macOS 12+ ou Linux com Foundation).

Consultar um CNPJ no Swift

O endpoint é GET https://api.opencnpj.com.br/cnpj/{cnpj}. Envie o CNPJ com 14 caracteres, sem pontos, barra ou hífen. O exemplo abaixo consulta o CNPJ 06.990.590/0001-23:

import Foundation

struct Empresa: Decodable {
    let razaoSocial: String?
    let estabelecimento: Estabelecimento

    struct Estabelecimento: Decodable {
        let situacaoCadastral: String?
    }
}

let url = URL(string: "https://api.opencnpj.com.br/cnpj/06990590000123")!
let (data, response) = try await URLSession.shared.data(from: url)

guard (response as? HTTPURLResponse)?.statusCode == 200 else {
    throw URLError(.badServerResponse)
}

let decoder = JSONDecoder()
decoder.keyDecodingStrategy = .convertFromSnakeCase
let empresa = try decoder.decode(Empresa.self, from: data)

print(empresa.razaoSocial ?? "")
print(empresa.estabelecimento.situacaoCadastral ?? "")

Remover a máscara do CNPJ

Se o CNPJ vem formatado (06.990.590/0001-23) de um formulário, banco de dados ou planilha, limpe a pontuação antes de montar a URL. A mesma regra funciona para o CNPJ alfanumérico:

func limparCnpj(_ cnpj: String) -> String {
    String(cnpj.uppercased().filter { $0.isASCII && ($0.isLetter || $0.isNumber) })
}

let cnpj = limparCnpj("06.990.590/0001-23") // "06990590000123"

Campos mais usados da resposta

Campo	Conteúdo
`razao_social`	Nome empresarial
`estabelecimento.nome_fantasia`	Nome fantasia
`estabelecimento.situacao_cadastral`	`Ativa`, `Suspensa`, `Inapta`, `Baixada` ou `Nula`
`estabelecimento.atividade_principal`	CNAE principal, com código e descrição
`estabelecimento.cidade.nome` e `estabelecimento.estado.sigla`	Município e UF
`estabelecimento.cep`, `logradouro`, `numero`, `bairro`	Endereço
`simples.simples` e `simples.mei`	Opção pelo Simples Nacional e MEI
`socios`	Quadro de sócios e administradores

A lista completa de campos está na documentação da API.

Tratando erros

Verifique o status HTTP antes de ler o JSON. Swift: use (response as? HTTPURLResponse)?.statusCode.

Status	O que significa	O que fazer
`200`	CNPJ encontrado	Ler o JSON
`400`	Formato de CNPJ inválido	Conferir os 14 caracteres
`404`	CNPJ não encontrado na base	Informar ao usuário
`429`	Limite de requisições excedido	Aguardar e tentar de novo
`500`	Erro interno	Tentar novamente mais tarde

Os erros também vêm em JSON, com os campos status, titulo e detalhes.

Boas práticas

Defina um timeout na requisição, por exemplo com URLRequest.timeoutInterval.
Guarde o resultado em cache se o mesmo CNPJ for consultado com frequência.
Em processamentos em lote, respeite o limite de 10 requisições por segundo.
Os dados refletem a base pública mais recente processada e não substituem certidões oficiais.

Perguntas frequentes

A API de CNPJ do openCNPJ é gratuita?

Sim, 100% grátis. Não há chave de acesso nem cadastro. O limite é de 10 requisições por segundo por IP.

Preciso configurar o App Transport Security?

Não. A API usa HTTPS, que já é aceito pelo ATS sem exceções.

Como lidar com campos que podem vir nulos?

Declare as propriedades como opcionais (String?). Vários campos da resposta podem ser null quando a fonte não tem a informação.

De onde vêm os dados do CNPJ?

Dos dados abertos do CNPJ publicados pela Receita Federal, complementados por bases públicas. Os dados podem ter defasagem e não substituem certidões oficiais. Veja a origem dos dados.