Skip to main content
POST
/
GuardaNFe
/
NFesCanceladas
Consultar Canceladas
curl --request POST \
  --url https://api.validanfe.com/GuardaNFe/NFesCanceladas \
  --header 'Content-Type: application/json' \
  --data '
{
  "periodMonths": 123,
  "cnpj": "<string>"
}
'

​
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.
Funcionalidade AvançadaA 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.

​
Endpoint

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

​
Headers

HeaderValorObrigatório
X-API-KEYSeu token de API✅ Sim
Content-Typeapplication/json✅ Sim

​
Parâmetros de Entrada

​
periodMonths
integer
default:"12"
Período em meses para buscar NFes canceladas (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

​
Exemplo de Requisição com Raiz CNPJ

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

​
Resposta

Exemplo de Resposta
{
  "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

CampoTipoDescrição
totalCountintegerTotal de NFes canceladas encontradas
periodoAnalisadointegerPeríodo analisado em meses
dataConsultadatetimeData e hora da consulta
nfesarrayLista de NFes canceladas
resumoEventosobjectResumo por tipo de evento

​
NFes Canceladas

CampoTipoDescrição
chaveNFestringChave de acesso da NFe
cnpjEmitentestringCNPJ do emitente
razaoSocialEmitentestringRazão social do emitente
cnpjDestinatariostringCNPJ do destinatário
razaoSocialDestinatariostringRazão social do destinatário
dataEmissaodatetimeData de emissão da NFe
valorTotaldecimalValor total da NFe
numeroNFestringNúmero da NFe
serieNFestringSérie da NFe
ufEmitentestringUF do emitente
ufDestinatariostringUF do destinatário
totalEventosintegerTotal de eventos da NFe
eventosarrayLista de eventos de cancelamento

​
Eventos de Cancelamento

CampoTipoDescrição
cnpjAutorstringCNPJ de quem executou o cancelamento
nomeAutorstringNome/Razão social do autor
justificativastringJustificativa do cancelamento
protocolostringProtocolo do evento na SEFAZ
statusstringStatus do evento

​
Casos de Uso

Auditoria Empresarial

Análise de Grupo EmpresarialUse a raiz CNPJ para auditar cancelamentos de todas as empresas do mesmo grupo

Análise de Risco

Comportamento FiscalAvalie padrões de cancelamento para análise de risco de crédito

​
Tipos de Busca

{
  "cnpj": "10989834"
}
Busca todas as empresas cujo CNPJ inicie com “10989834”:
  • 10989834000123 (Matriz)
  • 10989834000456 (Filial 1)
  • 10989834000789 (Filial 2)

​
Códigos de Erro

CódigoDescrição
400Parâmetros inválidos (período maior que 24 meses)
401Token de API inválido ou ausente
404Nenhuma NFe cancelada encontrada
500Erro interno do servidor
Serviço Sob DemandaO GuardaNFe deve estar ativado em sua conta. Entre em contato com o suporte se não tiver acesso.
Dica de PerformanceUse raiz CNPJ (8 dígitos) para análises amplas de grupos empresariais e CNPJ completo (14 dígitos) para consultas específicas.