@spec create_list(
  keyword() | map(),
  keyword()
) :: {:ok, Cnpja.CnpjList.t()} | {:error, Cnpja.Error.t()}

Creates a saved CNPJ list on the account (up to 1000 lists).

Attributes

• :title — required
• :description — optional
• :items — list of 14-digit CNPJs (mutually exclusive with :query)
• :query — search filters (same keys as search_offices/1, or a map with API keys)
• :limit — max establishments when generating from :query

Example

{:ok, list} = Cnpja.create_list(
  title: "SP ativas",
  query: [state_in: ["SP"], status_in: [2]],
  limit: 1000
)

@spec create_list_export(String.t(), keyword() | map(), keyword()) ::
  {:ok, Cnpja.CnpjListExportId.t()} | {:error, Cnpja.Error.t()}

Starts an asynchronous export of a saved list (Excel + JSON zip).

Options (export job)

Pass enrichment options as the second argument (keyword or map):

• :simples / :simples_history
• :registrations / :registrations_source
• :suframa / :geocoding
• :strategy / :max_age / :max_stale

Example

{:ok, %{id: export_id}} =
  Cnpja.create_list_export(list_id, simples: true, geocoding: true)

{:ok, export} = Cnpja.get_list_export(list_id, export_id)
# poll until export.status == "COMPLETED"

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

Deletes a saved list.

@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 or CPF (rural producer)
• states — comma-separated state codes, "ALL" or "ORIGIN"

Options

• :source — data source: "AUTO" (default), "CCC" or "SINTEGRA"
• :strategy — cache strategy
• :max_age / :max_stale — cache age limits in days

Example

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

@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 (required for rural producer CPF)

@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).

The response includes members, offices, and Simples/MEI data when available. This endpoint has no query options in the Commercial API.

@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_list(
  String.t(),
  keyword()
) :: {:ok, Cnpja.CnpjList.t()} | {:error, Cnpja.Error.t()}

Fetches a saved list by id (includes items).

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

Fetches a single export job (status, progress, download links).

@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", "ORIGIN", or comma-separated state codes
• :registrations_source — IE source: "AUTO" (default), "CCC" or "SINTEGRA"
• :suframa — include SUFRAMA data
• :geocoding — include geographic coordinates
• :links — certificate links, comma-separated

• :strategy — cache strategy: "CACHE_IF_ERROR" | "CACHE_IF_FRESH" | "CACHE" | "ONLINE"

• :max_age — maximum cache age in days
• :max_stale — stale cache tolerance in days
• :sync — wait for credit settlement synchronously

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

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

Options

• :width — image width in pixels (80–640, default 640)
• :height — image height in pixels (80–640, default 640)
• :zoom — zoom level (1–20, default 17)
• :scale — pixel density multiplier (1–2, default 1)

• :type — map type: "roadmap" | "terrain" | "satellite" | "hybrid"

@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 (80–640, default 640)
• :height — image height in pixels (80–640, default 640)
• :fov — field of view in degrees (60–120, default 90)

@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.

Options

• :history — include previous Simples/MEI periods (true/false)
• :simples_history — alias for :history (kept for consistency with get_office/2)
• :strategy / :max_age / :max_stale / :sync — cache controls

@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_list_exports(
  String.t(),
  keyword()
) :: {:ok, Cnpja.CnpjListExportPage.t()} | {:error, Cnpja.Error.t()}

Lists export jobs for a saved list.

Options

• :token — pagination cursor
• :limit — page size

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

Searches saved lists on the account.

Options

• :token — pagination cursor
• :limit — page size (default 10)
• :search — term matched against title or description

@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 (1–1000, default 10)
• :names_in / :names_nin — include/exclude terms in trade name or company name
• :alias_in / :alias_nin — include/exclude terms in trade name only
• :company_name_in / :company_name_nin — include/exclude terms in company name
• :legal_nature_in / :legal_nature_nin — legal nature IDs (IBGE 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
• :simei_optant — enrolled as MEI
• :head_eq — true for headquarters only, false for branches only
• :status_in — status IDs (1=Nula, 2=Ativa, 3=Suspensa, 4=Inapta, 8=Baixada)
• :reason_in — reason IDs for status
• :status_date_gte / :status_date_lte — status date range (ISO 8601)
• :special_in — special status IDs
• :special_date_gte / :special_date_lte — special status date range
• :founded_gte / :founded_lte — opening date range (ISO 8601)
• :municipality_in / :municipality_nin — IBGE municipality codes
• :state_in — state abbreviations
• :zip_in — postal codes
• :zip_gte / :zip_lte — postal code range
• :district_in / :district_nin — neighbourhood terms
• :street_in / :street_nin — street name terms
• :country_in / :country_nin — M49 country codes
• :main_activity_in / :side_activity_in — CNAE codes
• :activity_in / :activity_nin — CNAE codes across main and side activities
• :has_phone — true/false for phone presence
• :has_email — true/false for e-mail presence

Lists of values are joined as comma-separated strings.

@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"
• :person_country_in / :person_country_nin — M49 country codes

@spec update_list(String.t(), keyword() | map(), keyword()) ::
  {:ok, Cnpja.CnpjList.t()} | {:error, Cnpja.Error.t()}

Updates a saved list (:title, :description, and/or :items).