---
title: "CNPJ Alfanumérico — Contratos e exemplos de payload"
description: "Exemplos de request/response por produto (Consultas, Cadastro de empresas, NF-e/NFC-e e Distribuição) para definir contratos de integração com CNPJ alfanumérico."
source_url: https://nfe.io/docs/release-notes/2026-3-cnpj-alfanumerico/contratos-payloads
last_updated: 2026-07-03
---

# CNPJ Alfanumérico — Contratos e exemplos de payload

Esta página reúne exemplos de **request** e **response** por produto, para você **definir os contratos** da sua integração com CNPJ alfanumérico.

:::info Sobre os exemplos
- Os CNPJs alfanuméricos usados (`12ABC345000188`, `12ABC34501DE35`) são **exemplos** — use os CNPJs de teste publicados para homologação.
- A principal mudança de contrato é o tipo do campo `federalTaxNumber`, que passa a ser sempre **texto** (`string`) no novo versionamento.
- Produtos cujo contrato ainda está **em definição** não são detalhados aqui, para não publicar um formato sujeito a mudança.
:::

---

## 1. Consultas (CNPJ / Inscrição Estadual)

Consulta é **read-only** (GET, sem corpo de request). Exemplos abaixo são respostas reais do ambiente de **homologação**.

### 1.1 Consulta de CNPJ — `basicInfo`

```bash
GET /v2/legalentities/basicInfo/{federalTaxNumber}

curl 'https://data.api.legalentities-homolog.nfe.one/v2/legalentities/basicInfo/670E5Z9W000118' \
  --header 'Authorization: <apiKey>'
```

Response `200` (`federalTaxNumber` como `string`):

```json
{
  "legalEntity": {
    "tradeName": "GOOD LINE",
    "name": "KALEDI DISTRIB DE ARTIGOS DE ESCRITORIO LTDA",
    "federalTaxNumber": "670E5Z9W000118",
    "size": "ME",
    "openedOn": "1987-04-08T03:00:00+00:00",
    "address": {
      "state": "PR",
      "city": { "code": "4106902", "name": "Curitiba" },
      "district": "Novo Mundo",
      "streetSuffix": "Rua",
      "street": "Maria Bueno",
      "number": "276",
      "postalCode": "81020-180",
      "country": "BRA"
    },
    "statusOn": "2005-06-11T00:00:00+00:00",
    "status": "Active",
    "issuedOn": "2026-12-12T00:00:00+00:00",
    "shareCapital": 20000.0,
    "economicActivities": [
      { "type": "Main", "code": 4751201, "description": "Comércio varejista especializado de equipamentos e suprimentos de informática" }
    ]
  }
}
```

### 1.2 Consulta de Inscrição Estadual — `stateTaxInfo`

```bash
GET /v2/legalentities/stateTaxInfo/{state}/{federalTaxNumber}

curl 'https://data.api.legalentities-homolog.nfe.one/v2/legalentities/stateTaxInfo/SP/KGKG99WE000159' \
  --header 'Authorization: <apiKey>'
```

Response `200`:

```json
{
  "legalEntity": {
    "name": "POSTO BRASIL DE PRES PRUDENTE LTDA",
    "federalTaxNumber": "KGKG99WE000159",
    "createdOn": "2026-12-12T00:00:00+00:00",
    "taxRegime": "Normal",
    "stateTaxes": [
      {
        "status": "Abled",
        "taxNumber": "562097935119",
        "statusOn": "1990-06-04T00:00:00",
        "openedOn": "1990-06-04T00:00:00",
        "code": "SP",
        "address": {
          "city": { "code": "3541406", "name": "Presidente Prudente" },
          "district": "Vila Santa Izabel",
          "additionalInformation": "B",
          "streetSuffix": "Rua",
          "street": "José Tarifa Conde",
          "number": "1124",
          "postalCode": "19020-540"
        },
        "economicActivities": [ { "type": "Main", "code": 4731800 } ],
        "nfe":  { "status": "Unabled", "description": "Não credenciado para emissão da NF-e" },
        "nfse": { "status": "Unknown", "description": "Situação desconhecida" },
        "cte":  { "status": "Unknown", "description": "A SEFAZ não fornece a informação" },
        "nfce": { "status": "Unknown", "description": "Situação desconhecida" }
      }
    ]
  }
}
```

### 1.3 Erros das Consultas

Identificador inválido — `400`:

```json
{ "errors": [ { "message": "cnpj is null, white space or not valid" } ] }
```

CNPJ alfanumérico válido não encontrado — `404` (sem busca em tempo real para alfa; ver [Consultas](/release-notes/2026-3-cnpj-alfanumerico/consultas)).

---

## 2. Cadastro de empresas (`/v3/companies`)

Novo versionamento = **v3**. Empresa com CNPJ alfanumérico consultada por uma versão atual (v1/v2) retorna `400` (ver 2.3).

### 2.1 Request — criação (`POST /v3/companies`)

```json
{
  "company": {
    "name": "EMPRESA ALFANUMERICA LTDA",
    "tradeName": "ALFA",
    "federalTaxNumber": "12ABC345000188",
    "taxRegime": "Isento",
    "address": {
      "state": "SP",
      "city": { "code": "3550308", "name": "Sao Paulo" },
      "district": "Centro",
      "street": "Rua das Flores",
      "number": "100",
      "postalCode": "01001000",
      "country": "BRA",
      "additionalInformation": ""
    }
  }
}
```

> `federalTaxNumber` é aceito como **`string`** (recomendado) ou **`number`** inteiro (compatibilidade). Número fracionário → `400`.

### 2.2 Response — `GET /v3/companies/{id}`

Mesmos campos da versão anterior **+ `accountId`**, com `federalTaxNumber` sempre `string`:

```json
{
  "id": "a1b2c3d4e5f6478090a1b2c3d4e5f678",
  "accountId": "...",
  "name": "EMPRESA ALFANUMERICA LTDA",
  "federalTaxNumber": "12ABC345000188",
  "taxRegime": "Isento",
  "address": { "state": "SP", "city": { "code": "3550308", "name": "Sao Paulo" }, "district": "Centro", "street": "Rua das Flores", "number": "100", "postalCode": "01001000" },
  "stateTaxes": [],
  "municipalTaxes": [],
  "status": "Active",
  "createdOn": "2026-12-12T00:00:00+00:00",
  "modifiedOn": "2026-12-12T00:00:00+00:00"
}
```

### 2.3 Erro — empresa alfa via versão atual (v1/v2)

`400 Bad Request`:

```json
{ "errors": [ { "code": 40002, "message": "Esta empresa contém CNPJ alfanumérico e requer a API v3; as rotas v1/v2 não suportam CNPJ alfanumérico." } ] }
```

---

## 3. NF-e / NFC-e (`/v3/companies/{companyId}/productinvoices`)

Novo versionamento = **v3**. A principal mudança é o `federalTaxNumber` como `string`; o restante do corpo de emissão segue o formato atual.

### 3.1 Request — emissão (participantes com CNPJ alfanumérico)

```json
{
  "issuer":    { "federalTaxNumber": "12ABC345000188" },
  "buyer":     { "type": "LegalEntity", "federalTaxNumber": "98XYZ123000158" },
  "transport": { "transportGroup": { "federalTaxNumber": "34HJK987000140" } }
}
```

### 3.2 Response — nota emitida (chave de acesso alfanumérica)

`federalTaxNumber` como `string` e **chave de acesso** com dígito verificador por Módulo-11 **ASCII−48**:

```json
{
  "accessKey": "35260612ABC345000188550010000000031100000037",
  "issuer": { "federalTaxNumber": "12ABC345000188" }
}
```

Webhook (novo versionamento, `apiVersion: 3`):

```json
{ "payload": { "apiVersion": 3, "issuer": { "federalTaxNumber": "18792479000101" }, "buyer": { "federalTaxNumber": "12ABC345000188" } } }
```

### 3.3 Erro — alfa via versão atual

- Consultar, por uma versão atual, uma nota emitida no novo versionamento → `404`:
  ```json
  { "message": "invoice not found" }
  ```
- A emissão por uma versão atual com emissor alfanumérico não é aceita (a empresa alfanumérica não existe nas versões atuais).

---

## 4. Distribuição de Documentos Fiscais (inbound)

O `federalTaxNumber` é entregue como **texto**; um CNPJ alfanumérico aparece como `string` nos mesmos campos (ex.: `"12ABC34501DE35"`). Exemplo de corpo (com valores numéricos para ilustrar a forma):

```json
{
  "issuer":  { "federalTaxNumber": "57622466000146" },
  "buyer":   { "federalTaxNumber": "99999999999999" },
  "company": { "federalTaxNumber": "99999999999999" }
}
```