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

# Gerar DANFE

> Gere DANFE em PDF a partir do XML da NFe armazenada no GuardaNFe

## Visão Geral

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

<api-endpoint method="get" url="/GuardaNFe/GerarDanfe/{chaveNfe}" />

## Parâmetros

<ParamField path="chaveNfe" type="string" required>
  Chave de acesso da NFe (44 caracteres numéricos)

  **Exemplo:** `35170608530528000184550000000154301000771561`
</ParamField>

## Headers

<ParamField header="X-API-KEY" type="string" required>
  Token de autenticação da API
</ParamField>

<ParamField header="Accept" type="string" default="application/pdf">
  Tipo de conteúdo aceito na resposta
</ParamField>

## Exemplos de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.validanfe.com/GuardaNFe/GerarDanfe/35170608530528000184550000000154301000771561',
    {
      method: 'GET',
      headers: {
        'Accept': 'application/pdf',
        'X-API-KEY': 'SEU_TOKEN_AQUI'
      }
    }
  );

  if (response.ok) {
    const blob = await response.blob();
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'danfe.pdf';
    a.click();
  }
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.validanfe.com/GuardaNFe/GerarDanfe/35170608530528000184550000000154301000771561"
  headers = {
      "Accept": "application/pdf",
      "X-API-KEY": "SEU_TOKEN_AQUI"
  }

  response = requests.get(url, headers=headers)

  if response.status_code == 200:
      with open('danfe.pdf', 'wb') as f:
          f.write(response.content)
      print("DANFE gerado com sucesso!")
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, 'https://api.validanfe.com/GuardaNFe/GerarDanfe/35170608530528000184550000000154301000771561');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Accept: application/pdf',
      'X-API-KEY: SEU_TOKEN_AQUI'
  ]);

  $pdfContent = curl_exec($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

  if ($httpCode === 200) {
      file_put_contents('danfe.pdf', $pdfContent);
      echo "DANFE gerado com sucesso!";
  }

  curl_close($ch);
  ?>
  ```
</CodeGroup>

## Códigos de Resposta

<ResponseField name="200" type="Success">
  DANFE gerado com sucesso - retorna arquivo PDF

  **Content-Type:** `application/pdf`

  **Content-Disposition:** `attachment; filename="danfe_{chaveNfe}.pdf"`
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Chave NFe inválida ou malformada
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Token de autenticação ausente ou inválido
</ResponseField>

<ResponseField name="404" type="Not Found">
  NFe não encontrada ou não pertence ao cliente
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Erro interno ao gerar DANFE
</ResponseField>

<ResponseField name="503" type="Service Unavailable">
  Serviço de geração de DANFE temporariamente indisponível
</ResponseField>

## Exemplos de Resposta

<CodeGroup>
  ```json 404 - Not Found theme={null}
  {
    "message": "NFe não encontrada ou não pertence ao cliente."
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "message": "Erro ao gerar DANFE.",
    "error": "Timeout na geração do PDF"
  }
  ```
</CodeGroup>

## Características do DANFE

<Accordion title="Formato e Layout">
  * **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
</Accordion>

<Accordion title="Informações Incluídas">
  * **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
</Accordion>

<Accordion title="Performance e Confiabilidade">
  * **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
</Accordion>

## Processo de Geração

<Steps>
  <Step title="Validação da NFe">
    Sistema verifica se a NFe existe e pertence ao cliente autenticado
  </Step>

  <Step title="Recuperação do XML">
    XML da NFe é recuperado do armazenamento seguro (AWS S3)
  </Step>

  <Step title="Processamento">
    XML é enviado para o serviço especializado de geração de DANFE
  </Step>

  <Step title="Geração do PDF">
    DANFE é gerado conforme layout oficial da Receita Federal
  </Step>

  <Step title="Entrega">
    PDF é retornado diretamente no response para download
  </Step>
</Steps>

## Rate Limiting

<Warning>
  **Limite de Requisições**

  Para 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
</Warning>

## Troubleshooting

<Accordion title="Problemas Comuns">
  **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
</Accordion>

<Accordion title="Monitoramento">
  **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
</Accordion>

## Integração com Frontend

### Visualização no Navegador

<CodeGroup>
  ```javascript Abrir no navegador theme={null}
  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');
    }
  }
  ```

  ```javascript Download automático theme={null}
  async function baixarDanfe(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);
      const a = document.createElement('a');
      a.href = url;
      a.download = `danfe_${chaveNfe}.pdf`;
      a.click();
      URL.revokeObjectURL(url);
    }
  }
  ```
</CodeGroup>

### React Component

```jsx React Hook theme={null}
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

<CardGroup cols={2}>
  <Card title="Enviar XML" href="/validanfe-api/api-guarda/guarda-enviar">
    Envie XMLs de NFe para o sistema
  </Card>

  <Card title="Verificar NFe" href="/validanfe-api/api-guarda/guarda-checkar">
    Verifique se uma NFe está armazenada
  </Card>

  <Card title="Gerar Arquivo" href="/validanfe-api/api-guarda/guarda-gerararquivo">
    Gere arquivos ZIP com múltiplas NFes
  </Card>

  <Card title="Visualizar XML" href="/validanfe-api/api-guarda/guarda-visualizar">
    Visualize o conteúdo XML da NFe
  </Card>
</CardGroup>

<Tip>
  **Dica de Performance**

  Para 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
</Tip>

<Note>
  **Precisa de Ajuda?**

  Entre em contato: [suporte@validanfe.com](mailto:suporte@validanfe.com)
</Note>