# `Cnpja`
[🔗](https://github.com/devaction-labs/cnpja_ex/blob/v0.1.2/lib/cnpja.ex#L1)

Elixir SDK for the CNPJá API.

All functions return `{:ok, struct}` on success or `{:error, %Cnpja.Error{}}` on failure.

## Configuration

Via `config.exs`:

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

Via option (multi-tenant):

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

## Example

    case Cnpja.get_office("37335118000180") do
      {:ok, office}                       -> office.alias
      {:error, %Cnpja.Error{status: 404}} -> "not found"
      {:error, %Cnpja.Error{status: 429, required: r}} -> "insufficient credits: #{r}"
      {:error, %Cnpja.Error{}}            -> "generic error"
    end

# `get_ccc`

```elixir
@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")

# `get_ccc_certificate`

```elixir
@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

# `get_company`

```elixir
@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

# `get_credit`

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

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

# `get_office`

```elixir
@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

# `get_office_map`

```elixir
@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

# `get_office_street_view`

```elixir
@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

# `get_person`

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

Looks up a person by their CNPJá ID.

# `get_rfb`

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

Queries establishment data directly from the Receita Federal.

# `get_rfb_certificate`

```elixir
@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

# `get_simples`

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

Queries Simples Nacional and MEI data for a company.

# `get_simples_certificate`

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

Returns the Simples Nacional enrollment declaration as a PDF binary.

# `get_suframa`

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

Queries SUFRAMA enrollment data for an establishment.

# `get_suframa_certificate`

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

Returns the SUFRAMA fiscal incentives certificate as a PDF binary.

# `get_zip`

```elixir
@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"

# `search_offices`

```elixir
@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

# `search_persons`

```elixir
@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)

---

*Consult [api-reference.md](api-reference.md) for complete listing*