CNPJAPI

Migrate from ReceitaWS to CNPJAPI

Already integrating ReceitaWS? CNPJAPI replies in the same format, field by field. The migration is drop-in: swap the host of your call and your JSON-parsing code stays the same. This guide walks you through it.

What changes (and what doesn't)

  • The host changes: www.receitaws.com.br becomes api.cnpjapi.com.br.
  • Authentication changes: CNPJAPI requires your API key in the Authorization: Bearer header. Create your account at https://app.cnpjapi.com.br and generate the key (see Authentication).
  • The JSON body does not change: the same field names, in the same place (nome, fantasia, situacao, atividade_principal, qsa, ...). Your parser stays the same.

Step by step

Before (ReceitaWS)

curl https://www.receitaws.com.br/v1/cnpj/00776574000156

After (CNPJAPI)

curl https://api.cnpjapi.com.br/v1/cnpj/00776574000156 \
  -H "Authorization: Bearer cnpj_your_key"

The GET /v1/cnpj/{cnpj} path mirrors the ReceitaWS URL - migrating is swapping the host and adding the header. Alternatively, the canonical endpoint accepts GET /{cnpj}?formato=receitaws, with the same compatible response.

Code example

The Node examples use native fetch (Node 18+) and top-level await - run them as an ES module (.mjs, or "type": "module" in package.json), or wrap the code in an async function.

Node.js (only the host and the header change versus your current code):

const cnpj = "00776574000156";
const response = await fetch(`https://api.cnpjapi.com.br/v1/cnpj/${cnpj}`, {
  headers: { Authorization: "Bearer cnpj_your_key" },
});
const company = await response.json();
console.log(company.nome, company.situacao); // same fields as ReceitaWS

Python:

import requests

cnpj = "00776574000156"
r = requests.get(
    f"https://api.cnpjapi.com.br/v1/cnpj/{cnpj}",
    headers={"Authorization": "Bearer cnpj_your_key"},
)
company = r.json()
print(company["nome"], company["situacao"])  # same fields as ReceitaWS

Things to watch

The goal is property parity - the same field names, in the same place. A few details inherited from ReceitaWS:

  • status is "OK" on success and "ERROR" on error ({"status":"ERROR","message":"..."}).
  • atividades_secundarias with no items carries the sentinel [{"code":"00.00-0-00","text":"Não informada"}], just like ReceitaWS.
  • simples and simei are always present (fields come false/null when the company is not opted in).
  • ReceitaWS's proprietary billing field is omitted.
  • When you exceed the limit, the response is 429 with the Retry-After header (see Limits and plans).

The full table of differences is in ReceitaWS-compatible.

Batch lookup

The compatible mode also applies to batch - up to 20 CNPJs in a single call, in the same format. See Batch lookup.

Next steps

Create your free account at https://app.cnpjapi.com.br and migrate from ReceitaWS by swapping only the host.