@spec get_ccc(String.t(), String.t(), keyword()) ::
  {:ok, Cnpja.Ccc.t()} | {:error, Cnpja.Error.t()}

Queries state registrations from the CCC for the given states.

Parameters

• tax_id — full 14-digit CNPJ
• states — comma-separated state codes or "ALL"

Example

{:ok, ccc} = Cnpja.get_ccc("37335118000180", "SP,MG")

@spec get_ccc_certificate(
  String.t(),
  keyword()
) :: {:ok, binary()} | {:error, Cnpja.Error.t()}

Returns the CCC fiscal regularity certificate as a PDF binary.

Options

• :state — specific state code to filter the certificate

@spec get_company(
  String.t(),
  keyword()
) :: {:ok, Cnpja.Company.t()} | {:error, Cnpja.Error.t()}

Looks up a company by the first 8 digits of the CNPJ (root).

Options

• :simples — include Simples Nacional data
• :simples_history — include Simples Nacional history

@spec get_credit(keyword()) :: {:ok, Cnpja.Credit.t()} | {:error, Cnpja.Error.t()}

Returns the credit balance for the account associated with the API key.

@spec get_office(
  String.t(),
  keyword()
) :: {:ok, Cnpja.Office.t()} | {:error, Cnpja.Error.t()}

Looks up an establishment by its full 14-digit CNPJ.

Options

• :simples — include Simples Nacional data
• :simples_history — include Simples Nacional history
• :registrations — state registrations: "ALL", "NONE", or comma-separated state codes
• :registrations_source — IE source: "CCC" (default) or "RECEIPTS"
• :suframa — include SUFRAMA data
• :geocoding — include geographic coordinates
• :links — certificate links, comma-separated

• :strategy — cache strategy: "CACHE_IF_ERROR" | "NO_CACHE" | "CACHE"

• :max_age — maximum cache age in days
• :max_stale — stale cache tolerance in days

@spec get_office_map(
  String.t(),
  keyword()
) :: {:ok, binary()} | {:error, Cnpja.Error.t()}

Returns the map image of the establishment location (PNG binary).

Options

• :width — image width in pixels
• :height — image height in pixels
• :zoom — zoom level
• :scale — scale factor
• :type — map type

@spec get_office_street_view(
  String.t(),
  keyword()
) :: {:ok, binary()} | {:error, Cnpja.Error.t()}

Returns the Street View image of the establishment (JPEG binary).

Options

• :width — image width in pixels
• :height — image height in pixels
• :fov — field of view angle

@spec get_person(
  String.t(),
  keyword()
) :: {:ok, Cnpja.Person.t()} | {:error, Cnpja.Error.t()}

Looks up a person by their CNPJá ID.

@spec get_rfb(
  String.t(),
  keyword()
) :: {:ok, Cnpja.Rfb.t()} | {:error, Cnpja.Error.t()}

Queries establishment data directly from the Receita Federal.

@spec get_rfb_certificate(
  String.t(),
  keyword()
) :: {:ok, binary()} | {:error, Cnpja.Error.t()}

Returns the Comprovante de Inscrição e de Situação Cadastral as a PDF binary.

Options

• :pages — pages to include: "REGISTRATION", "MEMBERS", or both comma-separated

@spec get_simples(
  String.t(),
  keyword()
) :: {:ok, Cnpja.Simples.t()} | {:error, Cnpja.Error.t()}

Queries Simples Nacional and MEI data for a company.

@spec get_simples_certificate(
  String.t(),
  keyword()
) :: {:ok, binary()} | {:error, Cnpja.Error.t()}

Returns the Simples Nacional enrollment declaration as a PDF binary.

@spec get_suframa(
  String.t(),
  keyword()
) :: {:ok, Cnpja.Suframa.t()} | {:error, Cnpja.Error.t()}

Queries SUFRAMA enrollment data for an establishment.

@spec get_suframa_certificate(
  String.t(),
  keyword()
) :: {:ok, binary()} | {:error, Cnpja.Error.t()}

Returns the SUFRAMA fiscal incentives certificate as a PDF binary.

@spec get_zip(
  String.t(),
  keyword()
) :: {:ok, Cnpja.Zip.t()} | {:error, Cnpja.Error.t()}

Looks up a Brazilian postal code (CEP).

Example

{:ok, zip} = Cnpja.get_zip("01310100")
zip.city  #=> "São Paulo"

@spec search_offices(keyword()) ::
  {:ok, Cnpja.OfficeSearch.t()} | {:error, Cnpja.Error.t()}

Searches establishments with filters.

Options

• :token — pagination cursor (mutually exclusive with all filters)
• :limit — results per page
• :alias_in / :alias_nin — include/exclude trade name terms
• :company_name_in / :company_name_nin — include/exclude company name terms
• :legal_nature_in / :legal_nature_nin — legal nature codes
• :equity_gte / :equity_lte — share capital range
• :size_in — company size IDs (1=ME, 3=EPP, 5=Other)
• :simples_optant — enrolled in Simples Nacional (true/false)
• :simei_optant — enrolled as MEI (true/false)
• :head — headquarters only
• :status_in — status codes (2=Active, 3=Suspended, 4=Unfit, 8=Closed)
• :municipality_in / :state_in / :zip_in — location filters
• :main_activity_in / :side_activity_in — CNAE filters
• :has_phone / :has_email — contact presence filters

@spec search_persons(keyword()) ::
  {:ok, Cnpja.PersonSearch.t()} | {:error, Cnpja.Error.t()}

Searches persons with filters.

Options

• :token — pagination cursor (mutually exclusive with all filters)
• :limit — results per page
• :type_in — person types: "NATURAL", "LEGAL", "FOREIGN", "UNKNOWN" (comma-separated)
• :name_in / :name_nin — include/exclude name terms
• :tax_id_in — partial CPF digits (positions 4–9, comma-separated)
• :age_in — age ranges, e.g. "21-30,31-40"
• :country_in — M49 country codes (comma-separated)