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

# Risco CFOP

> Consulte NFes classificadas por risco FIDC usando CNPJ ou raiz CNPJ no GuardaNFe

## Consultar NFes por Classificação de Risco

Este endpoint permite consultar **NFes classificadas por risco FIDC** armazenadas no GuardaNFe utilizando **CNPJ específico** ou **raiz CNPJ** para análise de crédito e risco empresarial.

<Info>
  **Classificação FIDC**

  As NFes são classificadas em **3 grupos de risco** baseados nos CFOPs:

  * 🟢 **Baixo Risco**: Venda efetiva, crédito líquido e certo
  * 🟡 **Médio Risco**: Venda com incentivos, ST, triangulações ou consignação
  * 🔴 **Alto Risco**: Sem entrega ou crédito condicional
</Info>

## Endpoint

<CodeGroup>
  ```bash cURL theme={null}
  POST https://api.validanfe.com/GuardaNFe/ConsultarNFeRisco
  ```
</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="6" required>
  Período em meses para análise de risco (mínimo: 1, 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>

<ParamField body="pagina" type="integer" default="1">
  **Número da página** para paginação (inicia em 1)

  * **Tamanho fixo**: 50 registros por página
  * **Mínimo**: 1
</ParamField>

## Exemplo de Requisição com Raiz CNPJ

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

  ```json Payload Raiz CNPJ theme={null}
  {
    "periodMonths": 6,
    "cnpj": "10989834",
    "pagina": 1
  }
  ```
</CodeGroup>

## Exemplo de Requisição com CNPJ Específico

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

  ```json Payload CNPJ Específico theme={null}
  {
    "periodMonths": 12,
    "cnpj": "10989834000123",
    "pagina": 2
  }
  ```
</CodeGroup>

<Note>
  **Flexibilidade de Busca**

  * **Raiz CNPJ (8 dígitos)**: Analisa **todo o grupo empresarial**
  * **CNPJ Completo (14 dígitos)**: Analisa **empresa específica**
</Note>

## 📄 Paginação

<Info>
  **Sistema de Paginação**

  A API implementa paginação automática com **50 registros por página**:

  * ✅ **Página padrão**: Página 1 se não especificado
  * ✅ **Tamanho fixo**: 50 NFes por página para otimização
  * ✅ **Controle total**: Informações completas de navegação
  * ✅ **Performance**: Evita timeouts em consultas grandes
</Info>

### Exemplos de Navegação

```json Primeira Página theme={null}
{
  "periodMonths": 6,
  "cnpj": "10989834",
  "pagina": 1
}
```

```json Segunda Página   theme={null}
{
  "periodMonths": 6,
  "cnpj": "10989834", 
  "pagina": 2
}
```

## Resposta

```json Exemplo de Resposta theme={null}
{
  "totalCount": 850,
  "periodoAnalisado": 6,
  "dataConsulta": "2024-01-15T10:30:00Z",
  "paginacao": {
    "paginaAtual": 1,
    "totalPaginas": 17,
    "tamanhoPagina": 50,
    "temProximaPagina": true,
    "temPaginaAnterior": false
  },
  "grupos": {
    "riscoBaixo": [
      {
        "chaveNFe": "35240110989834000123550010000001234567890123",
        "cnpjEmitente": "10.989.834/0001-23",
        "razaoSocialEmitente": "EMPRESA MATRIZ LTDA",
        "cnpjDestinatario": "12.345.678/0001-90",
        "razaoSocialDestinatario": "CLIENTE EXEMPLO LTDA",
        "dataEmissao": "2024-01-10T14:20:00Z",
        "valorTotal": 2500.00,
        "numeroNFe": "123456",
        "cfop": "5101",
        "descricaoCFOP": "Venda de produção do estabelecimento",
        "classificacaoRisco": "Baixo"
      }
    ],
    "riscoMedio": [
      {
        "chaveNFe": "35240110989834000456550010000002345678901234",
        "cnpjEmitente": "10.989.834/0004-56",
        "razaoSocialEmitente": "EMPRESA FILIAL 01 LTDA",
        "cnpjDestinatario": "98.765.432/0001-11",
        "razaoSocialDestinatario": "OUTRO CLIENTE LTDA",
        "dataEmissao": "2024-01-12T09:15:00Z",
        "valorTotal": 1800.00,
        "numeroNFe": "234567",
        "cfop": "5116",
        "descricaoCFOP": "Venda de mercadoria adquirida ou recebida de terceiros, em venda à ordem",
        "classificacaoRisco": "Médio"
      }
    ],
    "riscoAlto": [
      {
        "chaveNFe": "35240110989834000789550010000003456789012345",
        "cnpjEmitente": "10.989.834/0007-89",
        "razaoSocialEmitente": "EMPRESA FILIAL 02 LTDA",
        "cnpjDestinatario": "11.222.333/0001-44",
        "razaoSocialDestinatario": "CLIENTE RISCO LTDA",
        "dataEmissao": "2024-01-14T16:45:00Z",
        "valorTotal": 5000.00,
        "numeroNFe": "345678",
        "cfop": "5922",
        "descricaoCFOP": "Lançamento efetuado a título de simples faturamento decorrente de venda para entrega futura",
        "classificacaoRisco": "Alto"
      }
    ],
    "totalRiscoBaixo": 520,
    "totalRiscoMedio": 230,
    "totalRiscoAlto": 100
  }
}
```

## Campos de Resposta

### Cabeçalho da Resposta

| Campo              | Tipo     | Descrição                                   |
| ------------------ | -------- | ------------------------------------------- |
| `totalCount`       | integer  | Total de NFes encontradas                   |
| `periodoAnalisado` | integer  | Período analisado em meses                  |
| `dataConsulta`     | datetime | Data e hora da consulta                     |
| `grupos`           | object   | NFes organizadas por classificação de risco |

### Grupos de Risco

| Campo             | Tipo    | Descrição                         |
| ----------------- | ------- | --------------------------------- |
| `riscoBaixo`      | array   | NFes de baixo risco               |
| `riscoMedio`      | array   | NFes de médio risco               |
| `riscoAlto`       | array   | NFes de alto risco                |
| `totalRiscoBaixo` | integer | Quantidade de NFes de baixo risco |
| `totalRiscoMedio` | integer | Quantidade de NFes de médio risco |
| `totalRiscoAlto`  | integer | Quantidade de NFes de alto risco  |

### NFes por Risco

| Campo                     | Tipo     | Descrição                                 |
| ------------------------- | -------- | ----------------------------------------- |
| `chaveNFe`                | string   | Chave de acesso da NFe                    |
| `cnpjEmitente`            | string   | CNPJ do emitente (formatado)              |
| `razaoSocialEmitente`     | string   | Razão social do emitente                  |
| `cnpjDestinatario`        | string   | CNPJ do destinatário (formatado)          |
| `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                             |
| `cfop`                    | string   | CFOP da operação                          |
| `descricaoCFOP`           | string   | Descrição oficial do CFOP                 |
| `classificacaoRisco`      | string   | Classificação: "Baixo", "Médio" ou "Alto" |

## Classificação de Risco por CFOP

<Tabs>
  <Tab title="🟢 Baixo Risco">
    **Venda efetiva, crédito líquido e certo**

    **CFOPs**: 5101, 5102, 6101, 6102, 5405, 6405, 5151, 6151, 5933, 6933

    * Vendas de mercadorias
    * Vendas de produção própria
    * Transferências de produção própria
    * Operações com baixo risco de inadimplência
  </Tab>

  <Tab title="🟡 Médio Risco">
    **Venda com incentivos, ST, triangulações ou consignação**

    **CFOPs**: 5116, 6116, 5117, 6117, 5401, 6401, 5402, 6402, 5949, 6949, 5910, 6910, 5911, 6911

    * Vendas com substituição tributária
    * Operações triangulares
    * Vendas em consignação
    * Operações com condições especiais
  </Tab>

  <Tab title="🔴 Alto Risco">
    **Sem entrega ou crédito condicional**

    **CFOPs**: 5922, 6922, 5923, 6923, 5912, 6912, 5913, 6913, 5914, 6914, 5915, 6915

    * Entregas futuras sem pagamento
    * Remessas para demonstração
    * Comodatos e empréstimos
    * Operações sem garantia de pagamento
  </Tab>
</Tabs>

## Casos de Uso

<CardGroup cols={2}>
  <Card title="Análise de Crédito FIDC" icon="chart-line">
    **Avaliação de Risco de Crédito**

    Use a classificação de risco para avaliar a qualidade do crédito baseado nos CFOPs das operações
  </Card>

  <Card title="Due Diligence Empresarial" icon="shield-check">
    **Análise de Grupo Empresarial**

    Avalie o perfil de risco de todo um grupo empresarial usando raiz CNPJ
  </Card>

  <Card title="Monitoramento de Carteira" icon="eye">
    **Gestão de Risco**

    Monitore mudanças no perfil de risco de clientes ao longo do tempo
  </Card>

  <Card title="Precificação de Produtos" icon="dollar-sign">
    **Pricing Baseado em Risco**

    Ajuste taxas e condições baseadas na classificação de risco das operações
  </Card>
</CardGroup>

## Tipos de Busca

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

    **Análise de Grupo Empresarial**

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

    * 10989834**000123** (Matriz)
    * 10989834**000456** (Filial 1)
    * 10989834**000789** (Filial 2)

    Ideal para **análise consolidada** de risco do grupo
  </Tab>

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

    **Análise Específica**

    Busca **apenas** a empresa específica "10989834000123"

    Ideal para **análise individual** de uma empresa específica
  </Tab>
</Tabs>

## Códigos de Erro

| Código | Descrição                                                     |
| ------ | ------------------------------------------------------------- |
| `400`  | Parâmetros inválidos (período inválido ou CNPJ mal formatado) |
| `401`  | Token de API inválido ou ausente                              |
| `404`  | Nenhuma NFe encontrada no período especificado                |
| `500`  | Erro interno do servidor                                      |

## Exemplos de Erro

```json Erro 400 - Parâmetros Inválidos theme={null}
{
  "errors": [
    "CNPJ deve ter 8 dígitos (raiz) ou 14 dígitos (completo)"
  ]
}
```

```json Erro 404 - Não Encontrado theme={null}
{
  "message": "Nenhuma NFe encontrada para o CNPJ 10989834 no período solicitado"
}
```

<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>
  **Otimização de Performance**

  * Use **períodos menores** (3-6 meses) para análises frequentes
  * Use **CNPJ específico** quando possível para consultas mais rápidas
  * A classificação é baseada no **primeiro CFOP** encontrado na NFe
</Tip>