Skip to main content
POST
https://api.validanfe.com
/
GuardaNFe
/
EnviarXml
Enviar XML
curl --request POST \
  --url https://api.validanfe.com/GuardaNFe/EnviarXml \
  --header 'Content-Type: <content-type>' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "xmlContent": "<string>",
  "nfeChave": "<string>",
  "metadata": {}
}
'
{
  "201": {},
  "400": {},
  "401": {},
  "403": {},
  "409": {},
  "413": {},
  "429": {},
  "500": {}
}

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.

Headers

X-API-KEY
string
required
Token de autenticação da API
Content-Type
string
required
Deve ser application/json

Parâmetros do Body

xmlContent
string
required
Conteúdo completo do arquivo XML da NFeFormato: String contendo o XML válido da NFe
nfeChave
string
required
Chave de acesso da NFe (44 caracteres)Exemplo: 35170608530528000184550000000154301000771561
metadata
object
Metadados adicionais para organizaçãoPropriedades opcionais:
  • origem: Origem do arquivo (ex: “email”, “upload”, “sistema”)
  • tags: Array de tags para categorização
  • observacoes: Observações adicionais

Exemplos de Requisição

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

Exemplo de Resposta

201 - Criado
{
  "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"
    }
  }
}
400 - Erro de Validação
{
  "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"
    }
  }
}
409 - NFe já existe
{
  "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

201
Created
NFe armazenada com sucesso
400
Bad Request
XML inválido, malformado ou chave NFe incorreta
401
Unauthorized
Token de autenticação ausente ou inválido
403
Forbidden
Serviço GuardaNFe não ativado para sua conta
409
Conflict
NFe já existe no sistema
413
Payload Too Large
Arquivo XML muito grande (limite: 5MB)
429
Too Many Requests
Limite de requisições excedido
500
Internal Server Error
Erro interno do servidor

Validações Realizadas

  • 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
  • Formato: 44 caracteres numéricos
  • Dígito Verificador: Validação matemática da chave
  • Consistência: Chave deve existir no conteúdo do XML
  • 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

Casos de Uso

Upload Manual

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

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

Serviço Não Ativado?Se você receber erro 403, entre em contato com [email protected] para ativar o GuardaNFe em sua conta.
Dica de PerformancePara uploads frequentes, considere implementar upload assíncrono e monitoramento via webhooks para melhor experiência do usuário.