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.

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

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):

{
  "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

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

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

Response 200:

{
  "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:

{ "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).

---

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)

{
  "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:

{
  "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:

{ "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)

{
  "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:

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

Webhook (novo versionamento, apiVersion: 3):

{ "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:

  { "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):

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