Webmania.AI.Validation.DFe 1.0.0

Validação de Documentos Fiscais com IA - SDK para C#/.NET

SDK oficial em C#/.NET para consumir a API de Validação de Documentos Fiscais com IA da WebmaniaBR. Valide NFe, NFCe, NFSe, CTe e MDFe através de imagens ou XML com tecnologia de inteligência artificial.

📋 Índice

• Instalação
  • Via NuGet
  • Via Docker
• Configuração Inicial
• Métodos Disponíveis
• Exemplos de Uso
  • Validação de Imagens
  • Validação de XML
  • Gerenciamento de Integrações
  • Consulta de Status
• Docker
  • Build e Execução
  • Exemplos com Docker
• Regras de Negócio
• Tratamento de Erros
• Requisitos
• Suporte
• Licença

🚀 Instalação

Via NuGet

# Package Manager
Install-Package Webmania.AI.Validation.DFe

# .NET CLI
dotnet add package Webmania.AI.Validation.DFe

# PackageReference
<PackageReference Include="Webmania.AI.Validation.DFe" Version="1.0.0" />

Via Docker

# Clone o repositório
git clone https://github.com/webmaniabr/IA-Validacao-DFe-C-Sharp.git
cd IA-Validacao-DFe-C-Sharp

# Build da imagem
docker build -t webmania/csharp-sdk .

# Executar
docker run --rm webmania/csharp-sdk

⚙️ Configuração Inicial

using Webmania.AI.Validation.DFe;

// Configuração básica
var client = new ValidationClient("SEU_TOKEN_API");

// Configuração com opções personalizadas
var client = new ValidationClient("SEU_TOKEN_API", new ValidationClientOptions
{
    Timeout = TimeSpan.FromSeconds(60)  // Timeout personalizado
});

📦 Métodos Disponíveis

💡 Exemplos de Uso

Validação de Imagens

Por URL (Síncrono - Uma Imagem)

var resultado = await client.ValidateImageByUrlAsync(
    "nfce", 
    new[] { "https://exemplo.com/nota-fiscal.jpg" },
    new Dictionary<string, object?>
    {
        ["formato"] = "json",
        ["assincrono"] = false
    }
);

Por URL (Assíncrono - Múltiplas Imagens)

var resultado = await client.ValidateImageByUrlAsync(
    "nfe", 
    new[] { 
        "https://exemplo.com/nota1.jpg",
        "https://exemplo.com/nota2.jpg" 
    },
    new Dictionary<string, object?>
    {
        ["formato"] = "json",
        ["url_notificacao"] = "https://seu-webhook.com/callback"
    }
);

Por Base64

var base64Image = Convert.ToBase64String(File.ReadAllBytes("nota.jpg"));

var resultado = await client.ValidateImageByBase64Async(
    "nfce",
    new[] { base64Image },
    new Dictionary<string, object?>
    {
        ["assincrono"] = true,
        ["url_notificacao"] = "https://seu-webhook.com/callback"
    }
);

Por Upload de Arquivo

var resultado = await client.ValidateImageUploadAsync(
    "nfe",
    new[] { 
        "/caminho/para/nota1.pdf",
        "/caminho/para/nota2.jpg" 
    },
    new Dictionary<string, object?>
    {
        ["url_notificacao"] = "https://seu-webhook.com/callback"
    }
);

Validação de XML

// Via arquivo
var resultado = await client.ValidateXmlAsync(
    "/caminho/para/nfe.xml",
    new Dictionary<string, object?>
    {
        ["modelo"] = "nfe",
        ["formato"] = "json"
    }
);

// Via conteúdo XML direto
var xmlContent = @"<?xml version=""1.0""?><NFe>...</NFe>";
var resultado = await client.ValidateXmlAsync(
    xmlContent,
    new Dictionary<string, object?>
    {
        ["modelo"] = "nfe"
    }
);

Gerenciamento de Integrações

// Registrar integração
var cadastro = await client.RegisterIntegrationAsync(
    "sefaz",
    new Dictionary<string, object?>
    {
        ["api_key"] = "sua_chave",
        ["api_secret"] = "seu_segredo"
    }
);

// Consultar integração
var integracao = await client.GetIntegrationAsync("sefaz");

// Remover integração
var remocao = await client.DeleteIntegrationAsync("sefaz");

Consulta de Status

// Consultar status de validação assíncrona
var status = await client.GetValidationLogAsync("uuid-da-validacao");

🐳 Docker

Build e Execução

# Build da imagem
docker build -t webmania/csharp-sdk .

# Ver instruções de uso
docker run --rm webmania/csharp-sdk

# Executar com token
docker run --rm \
  -e WEBMANIA_TOKEN="seu-token" \
  -e METHOD="help" \
  webmania/csharp-sdk

Exemplos com Docker

Validar Imagem por URL

# Validação síncrona (uma imagem)
docker run --rm \
  -e WEBMANIA_TOKEN="seu-token" \
  -e METHOD="ValidateImageByUrlAsync" \
  -e MODELO="nfce" \
  -e IMAGENS_URLS="https://exemplo.com/nota.jpg" \
  -e ASSINCRONO="false" \
  webmania/csharp-sdk

# Validação assíncrona (múltiplas imagens)
docker run --rm \
  -e WEBMANIA_TOKEN="seu-token" \
  -e METHOD="ValidateImageByUrlAsync" \
  -e MODELO="nfe" \
  -e IMAGENS_URLS="url1.jpg,url2.jpg,url3.jpg" \
  -e URL_NOTIFICACAO="https://webhook.site/..." \
  webmania/csharp-sdk

Validar com Base64

docker run --rm \
  -e WEBMANIA_TOKEN="seu-token" \
  -e METHOD="ValidateImageByBase64Async" \
  -e MODELO="nfce" \
  -e IMAGENS_BASE64="base64_string_aqui" \
  -e ASSINCRONO="true" \
  -e URL_NOTIFICACAO="https://webhook.site/..." \
  webmania/csharp-sdk

Upload de Arquivos Locais

docker run --rm \
  -v /seu/caminho/local:/images:ro \
  -e WEBMANIA_TOKEN="seu-token" \
  -e METHOD="ValidateImageUploadAsync" \
  -e MODELO="nfe" \
  -e FILE_PATHS="/images/nota1.jpg,/images/nota2.pdf" \
  -e URL_NOTIFICACAO="https://webhook.site/..." \
  webmania/csharp-sdk

Validar XML

# Com conteúdo XML direto
docker run --rm \
  -e WEBMANIA_TOKEN="seu-token" \
  -e METHOD="ValidateXmlAsync" \
  -e XML_CONTENT="<NFe>...</NFe>" \
  -e MODELO_XML="nfe" \
  -e FORMATO="json" \
  webmania/csharp-sdk

# Com arquivo XML montado
docker run --rm \
  -v /caminho/para/xml:/data:ro \
  -e WEBMANIA_TOKEN="seu-token" \
  -e METHOD="ValidateXmlAsync" \
  -e XML_FILE="/data/nota.xml" \
  -e MODELO_XML="nfe" \
  webmania/csharp-sdk

Consultar Status

docker run --rm \
  -e WEBMANIA_TOKEN="seu-token" \
  -e METHOD="GetValidationLogAsync" \
  -e UUID="uuid-da-validacao" \
  webmania/csharp-sdk

Modo Debug

docker run --rm \
  -e WEBMANIA_TOKEN="seu-token" \
  -e METHOD="ValidateImageByUrlAsync" \
  -e MODELO="nfce" \
  -e IMAGENS_URLS="https://exemplo.com/nota.jpg" \
  -e DEBUG="true" \
  webmania/csharp-sdk

Variáveis de Ambiente Docker

📝 Regras de Negócio

Processamento Assíncrono

• Uma imagem: Pode escolher entre síncrono ou assíncrono
• Múltiplas imagens: Sempre processado de forma assíncrona
• Formato texto: Sempre requer processamento assíncrono
• Assíncrono = true: Requer url_notificacao

Limites

• Máximo de 10 imagens por requisição
• Tamanho máximo por arquivo: 10 MB
• Formatos aceitos: JPEG, PNG, PDF
• Modelos aceitos para imagens: nfe, nfce, nfse
• Modelos aceitos para XML: nfe, nfce, cte, mdfe, nfse

🔧 Tratamento de Erros

try
{
    var resultado = await client.ValidateImageByUrlAsync(
        "nfce", 
        new[] { "https://exemplo.com/nota.jpg" }
    );
}
catch (ApiException ex)
{
    Console.WriteLine($"Erro API: {ex.Message}");
    Console.WriteLine($"Status: {ex.StatusCode}");
    Console.WriteLine($"Resposta: {ex.ResponseBody}");
}
catch (ArgumentException ex)
{
    Console.WriteLine($"Erro de validação: {ex.Message}");
}
catch (Exception ex)
{
    Console.WriteLine($"Erro geral: {ex.Message}");
}

✅ Requisitos

• .NET 6.0 ou superior
• Docker (opcional, para uso containerizado)
• Token de API válido da Webmania

📞 Suporte

• Documentação da API: https://webmaniabr.com/docs/
• Suporte técnico: https://webmaniabr.com/painel/
• Issues: GitHub Issues

📄 Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para detalhes.

WebmaniaBR © 2025 - Todos os direitos reservados