> ## Documentation Index
> Fetch the complete documentation index at: https://docs.validatech.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar Canceladas

> Consulte NFes canceladas por raiz CNPJ no GuardaNFe

## Consultar NFes Canceladas por Raiz CNPJ

Este endpoint permite consultar **NFes canceladas** armazenadas no GuardaNFe utilizando **raiz CNPJ** (8 dígitos) para buscar todas as empresas de um mesmo grupo empresarial.

<Info>
  **Funcionalidade Avançada**

  A consulta por **raiz CNPJ** permite encontrar NFes canceladas de todas as filiais de um grupo empresarial usando apenas os 8 primeiros dígitos do CNPJ.
</Info>

## Endpoint

<CodeGroup>
  ```bash cURL theme={null}
  POST https://api.validanfe.com/GuardaNFe/NFesCanceladas
  ```
</CodeGroup>

## Headers

| Header         | Valor              | Obrigatório |
| -------------- | ------------------ | ----------- |
| `X-API-KEY`    | Seu token de API   | ✅ Sim       |
| `Content-Type` | `application/json` | ✅ Sim       |

## Parâmetros de Entrada

<ParamField body="periodMonths" type="integer" default="12">
  Período em meses para buscar NFes canceladas (máximo: 24)
</ParamField>

<ParamField body="cnpj" type="string" required>
  **CNPJ ou raiz CNPJ** para filtrar:

  * **8 dígitos**: Raiz CNPJ (busca todas as filiais)
  * **14 dígitos**: CNPJ específico
</ParamField>

## Exemplo de Requisição com Raiz CNPJ

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://api.validanfe.com/GuardaNFe/NFesCanceladas' \
  --header 'X-API-KEY: VNFE-ce0e1-596ba288-fc80-4e72-8856-2ec533b0829a' \
  --header 'Content-Type: application/json' \
  --data '{
    "periodMonths": 12,
    "cnpj": "10989834"
  }'
  ```

  ```json Payload theme={null}
  {
    "periodMonths": 12,
    "cnpj": "10989834"
  }
  ```
</CodeGroup>

<Note>
  **Raiz CNPJ (8 dígitos)**

  Ao informar apenas 8 dígitos (ex: "10989834"), o sistema buscará **todas as empresas** cujo CNPJ **inicie** com estes dígitos, incluindo todas as filiais do grupo empresarial.
</Note>

## Resposta

```json Exemplo de Resposta theme={null}
{
  "totalCount": 15,
  "periodoAnalisado": 12,
  "dataConsulta": "2024-01-15T10:30:00Z",
  "nfes": [
    {
      "chaveNFe": "35240110989834000123550010000001234567890123",
      "cnpjEmitente": "10989834000123",
      "razaoSocialEmitente": "EMPRESA MATRIZ LTDA",
      "cnpjDestinatario": "12345678000190",
      "razaoSocialDestinatario": "CLIENTE EXEMPLO LTDA",
      "dataEmissao": "2024-01-10T14:20:00Z",
      "valorTotal": 1500.00,
      "numeroNFe": "123456",
      "serieNFe": "1",
      "ufEmitente": "SP",
      "ufDestinatario": "RJ",
      "totalEventos": 2,
      "eventos": [
        {
          "cnpjAutor": "10989834000123",
          "nomeAutor": "EMPRESA MATRIZ LTDA",
          "justificativa": "Erro no valor do produto",
          "protocolo": "135240001234567",
          "status": "Autorizado"
        }
      ]
    },
    {
      "chaveNFe": "35240110989834000456550010000002345678901234",
      "cnpjEmitente": "10989834000456",
      "razaoSocialEmitente": "EMPRESA FILIAL 01 LTDA",
      "cnpjDestinatario": "98765432000111",
      "razaoSocialDestinatario": "OUTRO CLIENTE LTDA",
      "dataEmissao": "2024-01-12T09:15:00Z",
      "valorTotal": 850.00,
      "numeroNFe": "234567",
      "serieNFe": "1",
      "ufEmitente": "SP",
      "ufDestinatario": "MG",
      "totalEventos": 1,
      "eventos": [
        {
          "cnpjAutor": "10989834000456",
          "nomeAutor": "EMPRESA FILIAL 01 LTDA",
          "justificativa": "Cancelamento por duplicidade",
          "protocolo": "135240001234568",
          "status": "Autorizado"
        }
      ]
    }
  ],
  "resumoEventos": {
    "Cancelamento": 10,
    "Operação não Realizada": 5
  }
}
```

## Campos de Resposta

### Cabeçalho da Resposta

| Campo              | Tipo     | Descrição                            |
| ------------------ | -------- | ------------------------------------ |
| `totalCount`       | integer  | Total de NFes canceladas encontradas |
| `periodoAnalisado` | integer  | Período analisado em meses           |
| `dataConsulta`     | datetime | Data e hora da consulta              |
| `nfes`             | array    | Lista de NFes canceladas             |
| `resumoEventos`    | object   | Resumo por tipo de evento            |

### NFes Canceladas

| Campo                     | Tipo     | Descrição                        |
| ------------------------- | -------- | -------------------------------- |
| `chaveNFe`                | string   | Chave de acesso da NFe           |
| `cnpjEmitente`            | string   | CNPJ do emitente                 |
| `razaoSocialEmitente`     | string   | Razão social do emitente         |
| `cnpjDestinatario`        | string   | CNPJ do destinatário             |
| `razaoSocialDestinatario` | string   | Razão social do destinatário     |
| `dataEmissao`             | datetime | Data de emissão da NFe           |
| `valorTotal`              | decimal  | Valor total da NFe               |
| `numeroNFe`               | string   | Número da NFe                    |
| `serieNFe`                | string   | Série da NFe                     |
| `ufEmitente`              | string   | UF do emitente                   |
| `ufDestinatario`          | string   | UF do destinatário               |
| `totalEventos`            | integer  | Total de eventos da NFe          |
| `eventos`                 | array    | Lista de eventos de cancelamento |

### Eventos de Cancelamento

| Campo           | Tipo   | Descrição                            |
| --------------- | ------ | ------------------------------------ |
| `cnpjAutor`     | string | CNPJ de quem executou o cancelamento |
| `nomeAutor`     | string | Nome/Razão social do autor           |
| `justificativa` | string | Justificativa do cancelamento        |
| `protocolo`     | string | Protocolo do evento na SEFAZ         |
| `status`        | string | Status do evento                     |

## Casos de Uso

<CardGroup cols={2}>
  <Card title="Auditoria Empresarial" icon="chart-line">
    **Análise de Grupo Empresarial**

    Use a raiz CNPJ para auditar cancelamentos de todas as empresas do mesmo grupo
  </Card>

  <Card title="Análise de Risco" icon="shield-check">
    **Comportamento Fiscal**

    Avalie padrões de cancelamento para análise de risco de crédito
  </Card>
</CardGroup>

## Tipos de Busca

<Tabs>
  <Tab title="Raiz CNPJ (8 dígitos)">
    ```json theme={null}
    {
      "cnpj": "10989834"
    }
    ```

    Busca **todas as empresas** cujo CNPJ inicie com "10989834":

    * 10989834**000123** (Matriz)
    * 10989834**000456** (Filial 1)
    * 10989834**000789** (Filial 2)
  </Tab>

  <Tab title="CNPJ Específico (14 dígitos)">
    ```json theme={null}
    {
      "cnpj": "10989834000123"
    }
    ```

    Busca **apenas** a empresa específica "10989834000123"
  </Tab>
</Tabs>

## Códigos de Erro

| Código | Descrição                                         |
| ------ | ------------------------------------------------- |
| `400`  | Parâmetros inválidos (período maior que 24 meses) |
| `401`  | Token de API inválido ou ausente                  |
| `404`  | Nenhuma NFe cancelada encontrada                  |
| `500`  | Erro interno do servidor                          |

<Warning>
  **Serviço Sob Demanda**

  O GuardaNFe deve estar **ativado** em sua conta. Entre em contato com o suporte se não tiver acesso.
</Warning>

***

<Tip>
  **Dica de Performance**

  Use **raiz CNPJ** (8 dígitos) para análises amplas de grupos empresariais e **CNPJ completo** (14 dígitos) para consultas específicas.
</Tip>