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

> Gere arquivo ZIP contendo XMLs das NFe armazenadas

## Objetivo

Este endpoint permite a **geração de um arquivo .zip** contendo os arquivos XML das NF-e correspondentes às chaves de acesso informadas. Você pode enviar uma ou múltiplas chaves na mesma requisição.

<Warning>
  **Para Operações em Larga Escala**

  Este endpoint é indicado para consultas pontuais ou pequenos volumes. Para recuperação de todo seu acervo fiscal, entre em contato com nosso suporte.
</Warning>

## Endpoint

<api-endpoint method="post" url="/GuardaNFe/GerarArquivo" />

## Headers

<ParamField header="Content-Type" type="string" default="application/json">
  Tipo de conteúdo da requisição
</ParamField>

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

## Body Parameters

<ParamField body="ChavesNFe" type="array" required>
  Lista de chaves de acesso das NF-e para incluir no arquivo ZIP

  **Exemplo:** `["35170608530528000184550000000154301000771561"]`
</ParamField>

## Exemplos de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.validanfe.com/GuardaNFe/GerarArquivo" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-API-KEY: SEU_TOKEN_AQUI" \
    -d '{
      "ChavesNFe": [
        "35170608530528000184550000000154301000771561",
        "22210841816302000110550000000000012824578529"
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.validanfe.com/GuardaNFe/GerarArquivo', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'X-API-KEY': 'SEU_TOKEN_AQUI'
    },
    body: JSON.stringify({
      ChavesNFe: [
        "35170608530528000184550000000154301000771561",
        "22210841816302000110550000000000012824578529"
      ]
    })
  });

  const resultado = await response.json();
  console.log('URL de Download:', resultado.downloadUrl);
  ```

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

  url = "https://api.validanfe.com/GuardaNFe/GerarArquivo"
  headers = {
      "Content-Type": "application/json",
      "Accept": "application/json",
      "X-API-KEY": "SEU_TOKEN_AQUI"
  }

  data = {
      "ChavesNFe": [
          "35170608530528000184550000000154301000771561",
          "22210841816302000110550000000000012824578529"
      ]
  }

  response = requests.post(url, headers=headers, data=json.dumps(data))
  resultado = response.json()

  print(f"URL de Download: {resultado['downloadUrl']}")
  ```

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

  $data = [
      "ChavesNFe" => [
          "35170608530528000184550000000154301000771561",
          "22210841816302000110550000000000012824578529"
      ]
  ];

  curl_setopt($ch, CURLOPT_URL, 'https://api.validanfe.com/GuardaNFe/GerarArquivo');
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Content-Type: application/json',
      'Accept: application/json',
      'X-API-KEY: SEU_TOKEN_AQUI'
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

  $response = curl_exec($ch);
  $resultado = json_decode($response, true);

  curl_close($ch);

  echo "URL de Download: " . $resultado['downloadUrl'];
  ?>
  ```
</CodeGroup>

## Códigos de Resposta

<ResponseField name="200" type="Success">
  ZIP gerado com sucesso, retorna URL para download
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Nenhuma chave NFe foi fornecida
</ResponseField>

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

<ResponseField name="500" type="Internal Server Error">
  Erro ao processar a requisição ou gerar o ZIP
</ResponseField>

## Exemplos de Resposta

<CodeGroup>
  ```json 200 - Sucesso theme={null}
  {
      "downloadUrl": "https://api.validanfe.com/GuardaNFe/Download/NFe_123456_abcdef123456.zip"
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
      "error": "Nenhuma chave NFe foi fornecida."
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
      "error": "Erro ao gerar o ZIP."
  }
  ```
</CodeGroup>

## Como Baixar o Arquivo

Após receber a resposta com sucesso, use a `downloadUrl` retornada para fazer o download:

<CodeGroup>
  ```bash cURL Download theme={null}
  curl -L -H "X-API-KEY: SEU_TOKEN_AQUI" \
    "https://api.validanfe.com/GuardaNFe/Download/NFe_123456_abcdef123456.zip" \
    --output nfe-arquivos.zip
  ```

  ```javascript JavaScript Download theme={null}
  const downloadResponse = await fetch(resultado.downloadUrl, {
    headers: {
      'X-API-KEY': 'SEU_TOKEN_AQUI'
    }
  });

  const blob = await downloadResponse.blob();
  const url = window.URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'nfe-arquivos.zip';
  document.body.appendChild(a);
  a.click();
  a.remove();
  ```

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

  download_response = requests.get(
      resultado['downloadUrl'],
      headers={'X-API-KEY': 'SEU_TOKEN_AQUI'}
  )

  with open('nfe-arquivos.zip', 'wb') as f:
      f.write(download_response.content)
  ```
</CodeGroup>

## Estrutura do Arquivo ZIP

O arquivo ZIP gerado contém:

<CardGroup cols={2}>
  <Card title="Organização">
    ```
    NFe_123456_abcdef123456.zip
    ├── 35170608...71561.xml
    ├── 22210841...78529.xml
    └── ...
    ```
  </Card>

  <Card title="Formato dos Arquivos">
    * **Nome**: Chave da NFe + `.xml`
    * **Conteúdo**: XML completo da NFe
    * **Encoding**: UTF-8
  </Card>
</CardGroup>

## Limitações e Considerações

<Accordion title="Limites de Volume">
  * **Máximo**: 100 chaves por requisição
  * **Tamanho**: Arquivos ZIP podem ter até 50MB
  * **Timeout**: Requisições com timeout de 60 segundos
</Accordion>

<Accordion title="Validade do Link">
  * Links de download são temporários
  * Válidos por **24 horas** após geração
  * Após expirar, gere um novo arquivo
</Accordion>

<Accordion title="Performance">
  * Tempo de geração varia com a quantidade de NFe
  * Processo assíncrono para grandes volumes
  * Arquivos ficam em cache por 1 hora
</Accordion>

<Info>
  **Dica de Uso**

  Para volumes maiores que 100 NFe, divida em múltiplas requisições ou entre em contato com o suporte para uma solução personalizada.
</Info>

<Tip>
  **Verificação Prévia**

  Use o endpoint [Verificar NFe](/validanfe-api/api-guarda/guarda-checkar) antes de gerar arquivos para confirmar quais NFe estão disponíveis.
</Tip>