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.
Token de autenticação da API
Deve ser application/json
Parâmetros do Body
Conteúdo completo do arquivo XML da NFe Formato: String contendo o XML válido da NFe
Chave de acesso da NFe (44 caracteres) Exemplo: 35170608530528000184550000000154301000771561
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
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
{
"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"
}
}
}
{
"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"
}
}
}
{
"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
NFe armazenada com sucesso
XML inválido, malformado ou chave NFe incorreta
Token de autenticação ausente ou inválido
Serviço GuardaNFe não ativado para sua conta
Arquivo XML muito grande (limite: 5MB)
Limite de requisições excedido
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 Performance Para uploads frequentes, considere implementar upload assíncrono e monitoramento via webhooks para melhor experiência do usuário.