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

# Enviar XML

> Envie arquivos XML de NFe para armazenamento seguro no GuardaNFe

## Visão Geral

Este endpoint permite enviar arquivos XML de Notas Fiscais Eletrônicas para armazenamento seguro no sistema GuardaNFe, garantindo a preservação e organização dos documentos fiscais.

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

## Headers

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

<ParamField header="Content-Type" type="string" required>
  Deve ser `application/json`
</ParamField>

## Parâmetros do Body

<ParamField body="xmlContent" type="string" required>
  Conteúdo completo do arquivo XML da NFe

  **Formato:** String contendo o XML válido da NFe
</ParamField>

<ParamField body="nfeChave" type="string" required>
  Chave de acesso da NFe (44 caracteres)

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

<ParamField body="metadata" type="object">
  Metadados adicionais para organização

  **Propriedades opcionais:**

  * `origem`: Origem do arquivo (ex: "email", "upload", "sistema")
  * `tags`: Array de tags para categorização
  * `observacoes`: Observações adicionais
</ParamField>

## Exemplos de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.validanfe.com/GuardaNFe/EnviarXml" \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: SEU_TOKEN_AQUI" \
    -d '{
      "xmlContent": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc xmlns=\"http://www.portalfiscal.inf.br/nfe\">...</nfeProc>",
      "nfeChave": "35170608530528000184550000000154301000771561",
      "metadata": {
        "origem": "upload",
        "tags": ["fornecedor-principal", "materiais"],
        "observacoes": "NFe recebida por email"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.validanfe.com/GuardaNFe/EnviarXml', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': 'SEU_TOKEN_AQUI'
    },
    body: JSON.stringify({
      xmlContent: xmlString, // Conteúdo do XML
      nfeChave: '35170608530528000184550000000154301000771561',
      metadata: {
        origem: 'sistema',
        tags: ['automatico'],
        observacoes: 'Processamento automático'
      }
    })
  });

  const resultado = await response.json();
  ```

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

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

  data = {
      "xmlContent": xml_content,  # Conteúdo do XML
      "nfeChave": "35170608530528000184550000000154301000771561",
      "metadata": {
          "origem": "sistema",
          "tags": ["automatico"],
          "observacoes": "Processamento automático"
      }
  }

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

  ```php PHP theme={null}
  <?php
  $url = "https://api.validanfe.com/GuardaNFe/EnviarXml";
  $headers = [
      "Content-Type: application/json",
      "X-API-KEY: SEU_TOKEN_AQUI"
  ];

  $data = [
      "xmlContent" => $xmlContent, // Conteúdo do XML
      "nfeChave" => "35170608530528000184550000000154301000771561",
      "metadata" => [
          "origem" => "sistema",
          "tags" => ["automatico"],
          "observacoes" => "Processamento automático"
      ]
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  $resultado = json_decode($response, true);
  curl_close($ch);
  ?>
  ```
</CodeGroup>

## Exemplo de Resposta

```json 201 - Criado theme={null}
{
  "success": true,
  "data": {
    "arquivoId": "123e4567-e89b-12d3-a456-426614174000",
    "nfeChave": "35170608530528000184550000000154301000771561",
    "status": "armazenado",
    "urlVisualizacao": "https://api.validanfe.com/GuardaNFe/Visualizar/123e4567-e89b-12d3-a456-426614174000",
    "urlDownload": "https://api.validanfe.com/GuardaNFe/Download/123e4567-e89b-12d3-a456-426614174000",
    "dataArmazenamento": "2024-03-10T15:30:45Z",
    "tamanhoArquivo": 15420,
    "hashMD5": "a1b2c3d4e5f6789012345678901234567890",
    "metadata": {
      "origem": "upload",
      "tags": ["fornecedor-principal", "materiais"],
      "observacoes": "NFe recebida por email"
    }
  }
}
```

```json 400 - Erro de Validação theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_XML",
    "message": "XML da NFe inválido ou malformado",
    "details": {
      "linha": 45,
      "coluna": 12,
      "erro": "Tag 'infNFe' não fechada corretamente"
    }
  }
}
```

```json 409 - NFe já existe theme={null}
{
  "success": false,
  "error": {
    "code": "NFE_ALREADY_EXISTS",
    "message": "Esta NFe já está armazenada no sistema",
    "details": {
      "arquivoExistente": "123e4567-e89b-12d3-a456-426614174000",
      "dataArmazenamento": "2024-03-05T10:20:30Z"
    }
  }
}
```

## Códigos de Resposta

<ResponseField name="201" type="Created">
  NFe armazenada com sucesso
</ResponseField>

<ResponseField name="400" type="Bad Request">
  XML inválido, malformado ou chave NFe incorreta
</ResponseField>

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

<ResponseField name="403" type="Forbidden">
  Serviço GuardaNFe não ativado para sua conta
</ResponseField>

<ResponseField name="409" type="Conflict">
  NFe já existe no sistema
</ResponseField>

<ResponseField name="413" type="Payload Too Large">
  Arquivo XML muito grande (limite: 5MB)
</ResponseField>

<ResponseField name="429" type="Too Many Requests">
  Limite de requisições excedido
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Erro interno do servidor
</ResponseField>

## Validações Realizadas

<Accordion title="Validação do XML">
  * **Estrutura XML**: Verifica se o XML está bem formado
  * **Schema NFe**: Valida contra o schema oficial da NFe
  * **Chave de Acesso**: Confirma que a chave no XML corresponde ao parâmetro
  * **Integridade**: Verifica assinatura digital se presente
</Accordion>

<Accordion title="Validação da Chave">
  * **Formato**: 44 caracteres numéricos
  * **Dígito Verificador**: Validação matemática da chave
  * **Consistência**: Chave deve existir no conteúdo do XML
</Accordion>

<Accordion title="Limitações">
  * **Tamanho máximo**: 5MB por arquivo XML
  * **Rate limiting**: 10 uploads por minuto
  * **Formatos aceitos**: Apenas XML válido de NFe
  * **Duplicatas**: Não permite NFe já armazenada
</Accordion>

## Casos de Uso

### Upload Manual

```javascript theme={null}
// Exemplo de upload manual via interface web
const uploadNFe = async (arquivoXML) => {
  const xmlContent = await arquivoXML.text();
  const chaveNFe = extrairChaveDoXML(xmlContent);
  
  const response = await fetch('/api/guardar-nfe', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': apiKey
    },
    body: JSON.stringify({
      xmlContent: xmlContent,
      nfeChave: chaveNFe,
      metadata: {
        origem: 'upload-manual',
        usuario: sessionUser.id
      }
    })
  });
  
  return await response.json();
};
```

### Processamento em Lote

```javascript theme={null}
// Exemplo de processamento em lote
const processarLoteNFe = async (arquivosXML) => {
  const resultados = [];
  
  for (const arquivo of arquivosXML) {
    try {
      const xmlContent = await arquivo.text();
      const chaveNFe = extrairChaveDoXML(xmlContent);
      
      const resultado = await enviarParaGuardaNFe({
        xmlContent,
        nfeChave: chaveNFe,
        metadata: {
          origem: 'lote',
          lote_id: gerarIdLote(),
          arquivo_original: arquivo.name
        }
      });
      
      resultados.push({
        arquivo: arquivo.name,
        sucesso: true,
        arquivoId: resultado.data.arquivoId
      });
      
    } catch (error) {
      resultados.push({
        arquivo: arquivo.name,
        sucesso: false,
        erro: error.message
      });
    }
  }
  
  return resultados;
};
```

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Verificar NFe" href="/validanfe-api/api-guarda/guarda-checkar">
    Confirme se a NFe foi armazenada corretamente
  </Card>

  <Card title="Visualizar NFe" href="/validanfe-api/api-guarda/guarda-visualizar">
    Acesse os dados da NFe armazenada
  </Card>

  <Card title="Gerar Arquivo" href="/validanfe-api/api-guarda/guarda-gerararquivo">
    Exporte suas NFe para download
  </Card>

  <Card title="Autenticação" href="/validanfe-api/autenticacao">
    Configure sua API key corretamente
  </Card>
</CardGroup>

<Warning>
  **Serviço Não Ativado?**

  Se você receber erro 403, entre em contato com [suporte@validanfe.com](mailto:suporte@validanfe.com) para ativar o GuardaNFe em sua conta.
</Warning>

<Tip>
  **Dica de Performance**

  Para uploads frequentes, considere implementar upload assíncrono e monitoramento via webhooks para melhor experiência do usuário.
</Tip>