cnpja_ex

Elixir SDK for the CNPJá API — real-time lookups for Brazilian CNPJ, CEP, Receita Federal, Simples Nacional, CCC, SUFRAMA, and more.

Installation

Add cnpja_ex to your dependencies in mix.exs:

def deps do
  [
    {:cnpja_ex, "~> 0.1.0"}
  ]
end

Configuration

# config/config.exs
config :cnpja_ex, api_key: System.get_env("CNPJA_API_KEY")

You can also pass the key per call (useful for multi-tenant apps):

Cnpja.get_office("37335118000180", api_key: "other-key")

Quick start

{:ok, office} = Cnpja.get_office("37335118000180")

office.alias          #=> "EMPRESA XYZ"
office.status.text    #=> "Ativa"
office.address.city   #=> "São Paulo"

Available functions

Function	Description
`Cnpja.get_credit/1`	Account credit balance
`Cnpja.get_zip/2`	Postal code (CEP) lookup
`Cnpja.get_company/2`	Company by CNPJ root (8 digits)
`Cnpja.get_office/2`	Establishment by full CNPJ (14 digits)
`Cnpja.get_office_map/2`	Establishment map image (PNG)
`Cnpja.get_office_street_view/2`	Street View image (JPEG)
`Cnpja.search_offices/1`	Search establishments with filters
`Cnpja.get_person/2`	Person by CNPJá ID
`Cnpja.search_persons/1`	Search persons with filters
`Cnpja.get_rfb/2`	Receita Federal establishment data
`Cnpja.get_rfb_certificate/2`	Comprovante de Situação Cadastral (PDF)
`Cnpja.get_simples/2`	Simples Nacional and MEI data
`Cnpja.get_simples_certificate/2`	Simples Nacional declaration (PDF)
`Cnpja.get_ccc/3`	State registrations from the CCC
`Cnpja.get_ccc_certificate/2`	CCC regularity certificate (PDF)
`Cnpja.get_suframa/2`	SUFRAMA enrollment data
`Cnpja.get_suframa_certificate/2`	SUFRAMA incentives certificate (PDF)

Error handling

All functions return {:ok, struct} or {:error, %Cnpja.Error{}}. No exceptions are raised.

case Cnpja.get_office("37335118000180") do
  {:ok, office} ->
    office.alias

  {:error, %Cnpja.Error{status: 404}} ->
    "not found"

  {:error, %Cnpja.Error{status: 429, required: required, remaining: remaining}} ->
    "insufficient credits — need #{required}, have #{remaining}"

  {:error, %Cnpja.Error{status: 401}} ->
    "invalid API key"

  {:error, %Cnpja.Error{status: 400, constraints: constraints}} ->
    "validation error: #{inspect(constraints)}"

  {:error, %Cnpja.Error{}} ->
    "unexpected error"
end

Options — `get_office/2`

Cnpja.get_office("37335118000180",
  simples: true,
  simples_history: true,
  registrations: "ALL",
  registrations_source: "CCC",
  suframa: true,
  geocoding: true,
  links: "RFB_CERTIFICATE,SIMPLES_CERTIFICATE",
  strategy: "CACHE_IF_ERROR",
  max_age: 45,
  max_stale: 365
)