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": {}
}
'import requests
url = "https://api.validanfe.com/GuardaNFe/EnviarXml"
payload = {
"xmlContent": "<string>",
"nfeChave": "<string>",
"metadata": {}
}
headers = {
"X-API-KEY": "<x-api-key>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': '<content-type>'},
body: JSON.stringify({xmlContent: '<string>', nfeChave: '<string>', metadata: {}})
};
fetch('https://api.validanfe.com/GuardaNFe/EnviarXml', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.validanfe.com/GuardaNFe/EnviarXml",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'xmlContent' => '<string>',
'nfeChave' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: <content-type>",
"X-API-KEY: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.validanfe.com/GuardaNFe/EnviarXml"
payload := strings.NewReader("{\n \"xmlContent\": \"<string>\",\n \"nfeChave\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<x-api-key>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.validanfe.com/GuardaNFe/EnviarXml")
.header("X-API-KEY", "<x-api-key>")
.header("Content-Type", "<content-type>")
.body("{\n \"xmlContent\": \"<string>\",\n \"nfeChave\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.validanfe.com/GuardaNFe/EnviarXml")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"xmlContent\": \"<string>\",\n \"nfeChave\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"201": {},
"400": {},
"401": {},
"403": {},
"409": {},
"413": {},
"429": {},
"500": {}
}API Guarda
Enviar XML
Envie arquivos XML de NFe para armazenamento seguro no GuardaNFe
POST
/
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": {}
}
'import requests
url = "https://api.validanfe.com/GuardaNFe/EnviarXml"
payload = {
"xmlContent": "<string>",
"nfeChave": "<string>",
"metadata": {}
}
headers = {
"X-API-KEY": "<x-api-key>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': '<content-type>'},
body: JSON.stringify({xmlContent: '<string>', nfeChave: '<string>', metadata: {}})
};
fetch('https://api.validanfe.com/GuardaNFe/EnviarXml', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.validanfe.com/GuardaNFe/EnviarXml",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'xmlContent' => '<string>',
'nfeChave' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: <content-type>",
"X-API-KEY: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.validanfe.com/GuardaNFe/EnviarXml"
payload := strings.NewReader("{\n \"xmlContent\": \"<string>\",\n \"nfeChave\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<x-api-key>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.validanfe.com/GuardaNFe/EnviarXml")
.header("X-API-KEY", "<x-api-key>")
.header("Content-Type", "<content-type>")
.body("{\n \"xmlContent\": \"<string>\",\n \"nfeChave\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.validanfe.com/GuardaNFe/EnviarXml")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"xmlContent\": \"<string>\",\n \"nfeChave\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"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
string
required
Token de autenticação da API
string
required
Deve ser
application/jsonParâmetros do Body
string
required
Conteúdo completo do arquivo XML da NFeFormato: String contendo o XML válido da NFe
string
required
Chave de acesso da NFe (44 caracteres)Exemplo:
35170608530528000184550000000154301000771561object
Metadados adicionais para organizaçãoPropriedades opcionais:
origem: Origem do arquivo (ex: “email”, “upload”, “sistema”)tags: Array de tags para categorizaçãoobservacoes: 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"
}
}'
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();
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
$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);
?>
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
Created
NFe armazenada com sucesso
Bad Request
XML inválido, malformado ou chave NFe incorreta
Unauthorized
Token de autenticação ausente ou inválido
Forbidden
Serviço GuardaNFe não ativado para sua conta
Conflict
NFe já existe no sistema
Payload Too Large
Arquivo XML muito grande (limite: 5MB)
Too Many Requests
Limite de requisições excedido
Internal Server Error
Erro interno do servidor
Validações Realizadas
Validação do XML
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
Validação da Chave
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
Limitações
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
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
Verificar NFe
Confirme se a NFe foi armazenada corretamente
Visualizar NFe
Acesse os dados da NFe armazenada
Gerar Arquivo
Exporte suas NFe para download
Autenticação
Configure sua API key corretamente
Serviço Não Ativado?Se você receber erro 403, entre em contato com suporte@validanfe.com 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.