Risco CFOP - ValidaNFe

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.

Classificação FIDCAs 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

Endpoint

POST https://api.validanfe.com/GuardaNFe/ConsultarNFeRisco

Headers

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

Parâmetros de Entrada

periodMonths

integer

default:"6"

required

Período em meses para análise de risco (mínimo: 1, máximo: 24)

cnpj

string

required

CNPJ ou raiz CNPJ para filtrar:

8 dígitos: Raiz CNPJ (busca todas as filiais)
14 dígitos: CNPJ específico

pagina

integer

default:"1"

Número da página para paginação (inicia em 1)

Tamanho fixo: 50 registros por página
Mínimo: 1

Exemplo de Requisição com Raiz CNPJ

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
}'

Exemplo de Requisição com CNPJ Específico

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
}'

Flexibilidade de Busca

Raiz CNPJ (8 dígitos): Analisa todo o grupo empresarial
CNPJ Completo (14 dígitos): Analisa empresa específica

📄 Paginação

Sistema de PaginaçãoA 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

Exemplos de Navegação

Primeira Página

{
  "periodMonths": 6,
  "cnpj": "10989834",
  "pagina": 1
}

Segunda Página

{
  "periodMonths": 6,
  "cnpj": "10989834", 
  "pagina": 2
}

Resposta

Exemplo de Resposta

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

🟢 Baixo Risco
🟡 Médio Risco
🔴 Alto Risco

Venda efetiva, crédito líquido e certoCFOPs: 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

Casos de Uso

Análise de Crédito FIDC

Avaliação de Risco de CréditoUse a classificação de risco para avaliar a qualidade do crédito baseado nos CFOPs das operações

Due Diligence Empresarial

Análise de Grupo EmpresarialAvalie o perfil de risco de todo um grupo empresarial usando raiz CNPJ

Monitoramento de Carteira

Gestão de RiscoMonitore mudanças no perfil de risco de clientes ao longo do tempo

Precificação de Produtos

Pricing Baseado em RiscoAjuste taxas e condições baseadas na classificação de risco das operações

Tipos de Busca

Raiz CNPJ (8 dígitos)
CNPJ Específico (14 dígitos)

{
  "cnpj": "10989834",
  "periodMonths": 6
}

Análise de Grupo EmpresarialBusca todas as empresas cujo CNPJ inicie com “10989834”:

10989834000123 (Matriz)
10989834000456 (Filial 1)
10989834000789 (Filial 2)

Ideal para análise consolidada de risco do grupo

{
  "cnpj": "10989834000123",
  "periodMonths": 12
}

Análise EspecíficaBusca apenas a empresa específica “10989834000123”Ideal para análise individual de uma empresa específica

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

Erro 400 - Parâmetros Inválidos

{
  "errors": [
    "CNPJ deve ter 8 dígitos (raiz) ou 14 dígitos (completo)"
  ]
}

Erro 404 - Não Encontrado

{
  "message": "Nenhuma NFe encontrada para o CNPJ 10989834 no período solicitado"
}

Serviço Sob DemandaO GuardaNFe deve estar ativado em sua conta. Entre em contato com o suporte se não tiver acesso.

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

​Consultar NFes por Classificação de Risco

​Endpoint

​Headers

​Parâmetros de Entrada

​Exemplo de Requisição com Raiz CNPJ

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

​📄 Paginação

​Exemplos de Navegação

​Resposta

​Campos de Resposta

​Cabeçalho da Resposta

​Grupos de Risco

​NFes por Risco

​Classificação de Risco por CFOP

​Casos de Uso

Análise de Crédito FIDC

Due Diligence Empresarial

Monitoramento de Carteira

Precificação de Produtos

​Tipos de Busca

​Códigos de Erro

​Exemplos de Erro

Consultar NFes por Classificação de Risco

Endpoint

Headers

Parâmetros de Entrada

Exemplo de Requisição com Raiz CNPJ

Exemplo de Requisição com CNPJ Específico

📄 Paginação

Exemplos de Navegação

Resposta

Campos de Resposta

Cabeçalho da Resposta

Grupos de Risco

NFes por Risco

Classificação de Risco por CFOP

Casos de Uso

Tipos de Busca

Códigos de Erro

Exemplos de Erro