Skip to main content
GET
/
GuardaNFe
/
GerarDanfe
/
{chaveNfe}
Gerar DANFE
curl --request GET \
  --url https://api.validanfe.com/GuardaNFe/GerarDanfe/{chaveNfe} \
  --header 'X-API-KEY: <x-api-key>'
{
  "200": {},
  "400": {},
  "401": {},
  "404": {},
  "500": {},
  "503": {}
}

​
Visão Geral

Gera um DANFE (Documento Auxiliar da Nota Fiscal Eletrônica) em formato PDF a partir de uma NFe armazenada no GuardaNFe.

​
Parâmetros

​
chaveNfe
string
required
Chave de acesso da NFe (44 caracteres numéricos)Exemplo: 35170608530528000184550000000154301000771561

​
Headers

​
X-API-KEY
string
required
Token de autenticação da API
​
Accept
string
default:"application/pdf"
Tipo de conteúdo aceito na resposta

​
Exemplos de Requisição

curl -X GET "https://api.validanfe.com/GuardaNFe/GerarDanfe/35170608530528000184550000000154301000771561" \
  -H "Accept: application/pdf" \
  -H "X-API-KEY: SEU_TOKEN_AQUI" \
  --output danfe_35170608530528000184550000000154301000771561.pdf

​
Códigos de Resposta

​
200
Success
DANFE gerado com sucesso - retorna arquivo PDFContent-Type: application/pdfContent-Disposition: attachment; filename="danfe_{chaveNfe}.pdf"
​
400
Bad Request
Chave NFe inválida ou malformada
​
401
Unauthorized
Token de autenticação ausente ou inválido
​
404
Not Found
NFe não encontrada ou não pertence ao cliente
​
500
Internal Server Error
Erro interno ao gerar DANFE
​
503
Service Unavailable
Serviço de geração de DANFE temporariamente indisponível

​
Exemplos de Resposta

{
  "message": "NFe não encontrada ou não pertence ao cliente."
}

​
Características do DANFE

  • Formato: PDF/A padrão para arquivamento
  • Layout: Conforme especificação oficial da Receita Federal
  • Orientação: Retrato (Portrait)
  • Tamanho: A4 (210 x 297 mm)
  • Resolução: 300 DPI para impressão de qualidade
  • Dados do Emitente: Razão social, CNPJ, endereço, IE
  • Dados do Destinatário: Nome, CPF/CNPJ, endereço
  • Produtos/Serviços: Descrição, quantidade, valores, impostos
  • Totais: Valores totais da nota, impostos, desconto
  • Observações: Informações adicionais da NFe
  • Chave de Acesso: Código de barras e número da chave
  • Timeout: 30 segundos na primeira tentativa
  • Retry Automático: Até 3 tentativas com timeout incremental
  • Cache: DANFE é gerado sob demanda
  • Fallback: Sistema robusto com múltiplas tentativas

​
Processo de Geração

1

Validação da NFe

Sistema verifica se a NFe existe e pertence ao cliente autenticado
2

Recuperação do XML

XML da NFe é recuperado do armazenamento seguro (AWS S3)
3

Processamento

XML é enviado para o serviço especializado de geração de DANFE
4

Geração do PDF

DANFE é gerado conforme layout oficial da Receita Federal
5

Entrega

PDF é retornado diretamente no response para download

​
Rate Limiting

Limite de RequisiçõesPara garantir a estabilidade do serviço:
  • 5 gerações por minuto por token
  • 50 gerações por hora por token
  • Limite pode ser aumentado conforme plano contratado

​
Troubleshooting

NFe não encontrada:
  • Verifique se a chave NFe está correta (44 dígitos)
  • Confirme se a NFe foi enviada via API de envio
  • Verifique se está usando o token correto
Timeout na geração:
  • Sistema faz retry automático
  • Tente novamente após alguns minutos
  • Entre em contato se persistir
PDF corrompido:
  • Verifique o Content-Type na resposta
  • Salve o arquivo em modo binário
  • Confirme que não houve truncamento
Métricas Importantes:
  • Tempo médio de geração: ~3-5 segundos
  • Taxa de sucesso: >99.5%
  • Timeout configurado: 30s/40s/50s (tentativas)
Logs de Auditoria:
  • Todas as gerações são registradas
  • Incluído no relatório de uso da API
  • Métricas disponíveis no dashboard

​
Integração com Frontend

​
Visualização no Navegador

async function visualizarDanfe(chaveNfe) {
  const response = await fetch(`/api/GuardaNFe/GerarDanfe/${chaveNfe}`, {
    headers: { 'X-API-KEY': 'SEU_TOKEN' }
  });
  
  if (response.ok) {
    const blob = await response.blob();
    const url = URL.createObjectURL(blob);
    window.open(url, '_blank');
  }
}

​
React Component

React Hook
import { useState } from 'react';

export function useDanfeGenerator() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const gerarDanfe = async (chaveNfe) => {
    setLoading(true);
    setError(null);
    
    try {
      const response = await fetch(`/api/GuardaNFe/GerarDanfe/${chaveNfe}`, {
        headers: { 'X-API-KEY': process.env.REACT_APP_API_TOKEN }
      });
      
      if (!response.ok) {
        throw new Error('Erro ao gerar DANFE');
      }
      
      const blob = await response.blob();
      const url = URL.createObjectURL(blob);
      window.open(url, '_blank');
      
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  };

  return { gerarDanfe, loading, error };
}

​
Base URL

A URL base para o GuardaNFe é: 
https://api.validanfe.com/GuardaNFe

​
Próximos Passos

Enviar XML

Envie XMLs de NFe para o sistema

Verificar NFe

Verifique se uma NFe está armazenada

Gerar Arquivo

Gere arquivos ZIP com múltiplas NFes

Visualizar XML

Visualize o conteúdo XML da NFe
Dica de PerformancePara aplicações que geram muitos DANFEs:
  • Implemente cache no frontend para evitar gerações duplicadas
  • Use loading states para melhor experiência do usuário
  • Considere geração em lote para múltiplas NFes
Precisa de Ajuda?Entre em contato: suporte@validanfe.com