Documentacao da API Nortfly

Visao geral

A API retorna dados estruturados da base publica organizada pela Nortfly e de bases brasileiras abertas consolidadas. O objetivo e permitir consulta legitima, comparacao comercial e atualizacao cadastral, sem transformar a plataforma em fonte de spam.

FormatoJSON

AutenticacaoX-Nortfly-Key

CustoSem creditos

1. Cadastre a empresaA chave gratuita exige uma empresa vinculada a conta.

2. Consulte CNPJ, CEP ou NCMInforme CNPJs, CEPs e codigos NCM com ou sem mascara.

3. Receba JSONDados publicos e dados premium liberados.

4. Audite o usoConsultas ficam registradas no painel sem consumir franquia.

Autenticacao

Envie sua chave no cabecalho HTTP X-Nortfly-Key. A chave completa aparece apenas uma vez no momento da criacao. Depois disso, a Nortfly armazena somente o hash da chave.

X-Nortfly-Key: nf_sua_chave_api

Nunca exponha a chave no frontend publico, em aplicativos sem backend, repositorios Git, prints ou extensoes de navegador. Use sempre no servidor.

Chave de acesso

Entre na sua conta para gerar e gerenciar sua chave de API.

Entrar para gerar chave

Status da base

O endpoint de status e publico e mostra a saude operacional da API, bases locais disponiveis, volume estimado de registros, indice de busca, gateways rapidos e bases brasileiras de referencia. Ele ajuda a conferir que a Nortfly usa base propria antes de integrar consultas em massa controladas.

GET https://nortfly.com.br/api/nortfly/v1/status

Endpoints principais

Consulta uma empresa pelo CNPJ no gateway rapido e retorna dados cadastrais, localizacao, atividade, URL publica Nortfly e dados premium quando disponiveis.

GET https://nortfly.com.br/api/nortfly/v1/empresas?cnpj=00000000000000

Consulta publica de CEP em rota rapida, compativel com ViaCEP e preparada para cache de borda. Use esta rota para autocomplete, checkout, ERPs, CRMs e preenchimento de formularios.

GET https://nortfly.com.br/ws/01001000/json/ GET https://nortfly.com.br/ws/01001000/xml/ GET https://nortfly.com.br/ws/SP/Sao%20Paulo/Paulista/json/

Consulta moderna de CEP com metadados Nortfly, geolocalizacao quando disponivel e resposta estendida.

GET https://nortfly.com.br/cep-api/v1/cep/01001000 GET https://nortfly.com.br/cep-api/v1/search?uf=SP&cidade=Sao%20Paulo&q=Paulista

Consulta autenticada de CEP no gateway rapido da API Nortfly v1, usando a mesma chave das APIs de CNPJ, GeoCEP e NCM.

GET https://nortfly.com.br/api/nortfly/v1/ceps?cep=01001000

Consulta latitude e longitude por CEP ou endereco no gateway rapido. A resposta inclui o nivel de precisao para diferenciar coordenadas aproximadas de coordenadas informadas pelo usuario.

GET https://nortfly.com.br/api/nortfly/v1/geocep?cep=01001000 GET https://nortfly.com.br/api/nortfly/v1/geocep?q=Rua%20Sete%20de%20Setembro%20Nova%20Friburgo

Consulta uma classificacao NCM por codigo exato ou por termo de busca no gateway rapido.

GET https://nortfly.com.br/api/nortfly/v1/ncm?q=cafe&limit=10 GET https://nortfly.com.br/api/nortfly/v1/ncm/21011110

Endpoint	Parametro	Descricao
/ws/{cep}/json	cep	Consulta publica rapida, compativel com ViaCEP, com JSON/JSONP.
/ws/{cep}/xml	cep	Consulta publica rapida em XML.
/ws/{uf}/{cidade}/{logradouro}/json	uf, cidade, logradouro	Busca reversa publica por endereco, limitada a 50 resultados.
/cep-api/v1/cep/{cep}	cep	Consulta publica moderna com geolocalizacao e metadados Nortfly.
/status	-	Status publico da API, bases locais e indice de busca.
/empresas	cnpj	CNPJ com 14 caracteres. Pode ser enviado com ou sem pontuacao e esta pronto para CNPJ alfanumerico.
/ceps	cep	CEP autenticado com 8 digitos. Pode ser enviado com ou sem hifen.
/geocep	cep ou q	Retorna endereco, latitude, longitude, fonte e precisao da geolocalizacao.
/ncm	q ou codigo	Retorna classificacoes NCM por termo ou por codigo exato.

Bases brasileiras

Rotas publicas de referencia para enriquecer sistemas, formularios, CRMs, ERPs e paineis sem depender de carregamento da area administrativa.

Base	Exemplo	Uso
Bancos	https://nortfly.com.br/api/nortfly/v1/banks/v1/001	Consulta banco por codigo COMPE ou ISPB.
Participantes PIX	https://nortfly.com.br/api/nortfly/v1/pix/v1/participants	Lista instituicoes participantes do PIX.
DDD	https://nortfly.com.br/api/nortfly/v1/ddd/v1/11	Retorna UF, cidades, IBGE e coordenadas por DDD.
Feriados	https://nortfly.com.br/api/nortfly/v1/feriados/v1/2026	Feriados nacionais por ano.
IBGE	https://nortfly.com.br/api/nortfly/v1/ibge/municipios/v1/SP	UFs e municipios com codigo IBGE, DDD e coordenadas.
Taxas	https://nortfly.com.br/api/nortfly/v1/taxas/v1/selic	Selic, CDI, IPCA, IGP-M e poupanca.
FIPE	https://nortfly.com.br/api/nortfly/v1/fipe/preco/v1/004278-1?tipo=carros	Tabelas, marcas, modelos, anos e preco por codigo FIPE.
ISBN	https://nortfly.com.br/api/nortfly/v1/isbn/v1/9788535902778	Consulta livro por ISBN.
Registro.br	https://nortfly.com.br/api/nortfly/v1/registrobr/v1/nortfly.com.br	Status, eventos e nameservers de dominios .br.
Cambio	https://nortfly.com.br/api/nortfly/v1/cambio/v1/cotacao/USD/2026-07-08	Cotacao PTAX com serie recente e ultima cotacao encontrada.
CPTEC cidades	https://nortfly.com.br/api/nortfly/v1/cptec/v1/cidade/sao%20paulo	Busca codigo CPTEC de cidade pela base local expandida.
Clima CPTEC	https://nortfly.com.br/api/nortfly/v1/cptec/v1/clima/previsao/244/4	Previsao por codigo de cidade, com cache curto e origem CPTEC/INPE.
Aeroportos	https://nortfly.com.br/api/nortfly/v1/aeroportos/v1?uf=SP&q=Guarulhos	Aeroportos brasileiros por nome, cidade, UF, ICAO ou IATA.
Clima de aeroporto	https://nortfly.com.br/api/nortfly/v1/aeroportos/v1/SBGR?clima=1	Condicoes meteorologicas CPTEC por codigo ICAO quando a fonte disponibiliza.

Uso, protecao e acesso

A API Nortfly esta disponivel para contas com empresa cadastrada. Consultas de CNPJ, CEP, GeoCEP e NCM usam a mesma chave, rodam no gateway rapido, nao consomem creditos e nao possuem franquia diaria ou mensal. Mantemos apenas protecao tecnica por minuto para preservar estabilidade.

Tipo	Acesso	Observacao
Conta gratuita com empresa cadastrada	API liberada	Permite consultar bases publicas sem consumo de creditos, com chave individual e registro de uso.
Plano verificado	API liberada com prioridade comercial	Recebe maior destaque na plataforma e pode ter protecao tecnica ajustada conforme necessidade operacional.
Seguranca	Controle operacional	Chaves individuais, logs, bloqueio por abuso e protecao por minuto ajudam a manter a API estavel.

Formato da resposta

A resposta de CNPJ traz dados publicos e um bloco premium com telefone, e-mail e socios quando disponiveis. O campo CNPJ retorna o identificador normalizado, mantendo compatibilidade com CNPJs numericos atuais e CNPJs alfanumericos quando forem usados. A resposta de CEP traz endereco estruturado e URL publica. A resposta de NCM traz codigo, descricao e hierarquia quando disponivel.

{
  "cnpj": "00000000000000",
  "razao_social": "EMPRESA EXEMPLO LTDA",
  "nome_fantasia": "EMPRESA EXEMPLO",
  "situacao_cadastral": "Ativa",
  "porte": "Microempresa (ME)",
  "cnae_principal": "1412601",
  "cnae_descricao": "Confeccao de pecas do vestuario",
  "municipio": "NOVA FRIBURGO",
  "uf": "RJ",
  "url": "https://nortfly.com.br/cnpj/00000000000000/",
  "premium": {
    "telefone": ["+55 (22) 99999-9999"],
    "email": ["[email protected]"],
    "socios": [
      {"nome": "NOME DO SOCIO", "qualificacao": "Socio-administrador"}
    ]
  },
  "usage": {
    "billable": false,
    "credits_consumed": 0,
    "rate_limit_per_minute": 600
  }
}

Resposta de CEP

A rota publica /ws retorna campos compativeis com ViaCEP. A rota /cep-api/v1 acrescenta metadados Nortfly e geolocalizacao quando disponivel.

{
  "cep": "01001-000",
  "logradouro": "Praca da Se",
  "complemento": "lado impar",
  "unidade": "",
  "bairro": "Se",
  "localidade": "Sao Paulo",
  "uf": "SP",
  "estado": "Sao Paulo",
  "regiao": "Sudeste",
  "ibge": "3550308",
  "gia": "",
  "ddd": "",
  "siafi": "",
  "cep_numerico": "01001000",
  "cep_formatado": "01001-000",
  "tipo_logradouro": "Praca",
  "nome_logradouro": "da Se",
  "cidade": "Sao Paulo",
  "tipo_cep": "logradouro",
  "fonte": "Correios eDNE",
  "url": "https://nortfly.com.br/cep/01001000/praca-da-se-sao-paulo-sp/",
  "usage": {
    "billable": false,
    "credits_consumed": 0,
    "rate_limit_per_minute": 600
  }
}

Codigos de erro

HTTP	Codigo	Quando acontece
400	nortfly_api_cnpj / nortfly_api_cep	CNPJ ou CEP ausente ou invalido.
401	nortfly_api_key_missing	Cabecalho X-Nortfly-Key nao informado.
401	nortfly_api_key_invalid	Chave inexistente, revogada ou incorreta.
403	nortfly_api_company_required	A conta ainda nao possui empresa cadastrada.
403	nortfly_api_plan	API temporariamente desativada para a configuracao atual da conta.
404	nortfly_api_not_found	CNPJ, CEP, endereco ou NCM nao encontrado na base.
429	nortfly_api_rate_minute	Protecao por minuto atingida.

Seguranca e antiabuso

Chaves sao armazenadas por hash, nao em texto puro.
Consultas por API exigem empresa cadastrada e chave ativa.
Todos os usos sao registrados com canal, usuario, consulta, IP em hash e user-agent.
A API nao consome creditos nem franquia diaria ou mensal.
Ha protecao por minuto configuravel no painel admin.
O cadastro de empresa reduz abuso por recriacao indevida de contas.

LGPD e uso permitido

A API deve ser usada para consulta empresarial legitima, verificacao cadastral, prospeccao responsavel, comparacao de mercado, analise de fornecedores e organizacao interna. A base vem de informacoes publicas e/ou publicamente disponibilizadas, mas o uso deve respeitar finalidade, necessidade, transparencia e direitos dos titulares.

Nao use a API para spam, envio massivo sem base legal, enriquecimento abusivo, raspagem sem controle, venda bruta de dados pessoais ou qualquer finalidade que viole LGPD, Marco Civil, politicas de plataformas de mensagem ou legislacao aplicavel.

Exemplos

cURL

curl -H "X-Nortfly-Key: nf_sua_chave_api" \
  "https://nortfly.com.br/api/nortfly/v1/empresas?cnpj=00000000000000"

curl "https://nortfly.com.br/ws/01001000/json/"

curl "https://nortfly.com.br/cep-api/v1/cep/01001000"

curl -H "X-Nortfly-Key: nf_sua_chave_api" \
  "https://nortfly.com.br/api/nortfly/v1/ncm?q=cafe&limit=10"

Status publico

curl "https://nortfly.com.br/api/nortfly/v1/status"

PHP

$ch = curl_init('https://nortfly.com.br/api/nortfly/v1/empresas?cnpj=00000000000000');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Nortfly-Key: nf_sua_chave_api'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript no backend Node.js

const res = await fetch('https://nortfly.com.br/api/nortfly/v1/empresas?cnpj=00000000000000', {
  headers: { 'X-Nortfly-Key': process.env.NORTFLY_API_KEY }
});
const data = await res.json();

Boas praticas de integracao

Use cache local para evitar consultar o mesmo CNPJ repetidamente.
Trate erros 429 com pausa e reprocessamento posterior.
Nunca rode loops agressivos. A API foi desenhada para consulta controlada.
Armazene apenas os dados necessarios para sua finalidade.
Mostre ao usuario a origem dos dados quando usar em sistemas externos.
Revogue chaves antigas quando trocar de fornecedor, funcionario ou sistema.