Pular para o conteúdo principal

SDK para .NET

Comece a usar rapidamente a Nuvem Fiscal com o nosso SDK para .NET! O SDK é uma biblioteca open source cujo código-fonte completo está disponível no GitHub:

Frameworks suportadas​

  • .NET Core >=1.0
  • .NET Framework >=4.6
  • Mono/Xamarin >=vNext

Instalação​

O SDK da Nuvem Fiscal para .NET está disponível no Nuget.

Para adicionar o SDK ao seu projeto, basta instalar o package NuvemFiscal.Sdk utilizando sua ferramenta preferida de gerenciamento de packages do Nuget.

Se preferir instalar a partir do console/terminal:

PM> Install-Package NuvemFiscal.Sdk

Ou a partir do .NET CLI (cross-platform:

dotnet add package NuvemFiscal.Sdk

Utilização​

Após adicionar o package NuvemFiscal.Sdk ao seu projeto C#, use os namespaces:

using NuvemFiscal.Sdk.Api;
using NuvemFiscal.Sdk.Client;
using NuvemFiscal.Sdk.Model;

Instanciando a API​

Cada ApiClass (mais especificamente o ApiClient dentro dela) irá criar uma instância de HttpClient, e irá usá-la durante todo o ciclo de vida da ApiClass, e fará um dispose quando o método Dispose for chamado.

Para melhor gerenciar as conexões, é uma boa prática reutilizar os objetos HttpClient e HttpClientHandler (visite here para mais informações). Para usar sua própria instância de HttpClient, simplesmente passe-a ao construtor da ApiClass. Também é importante habilitar a descompactação automática para conteúdos gzip, para ser possível receber XML e PDF (DANFE) via SDK:

HttpClientHandler httpClientHandler = new HttpClientHandler();
httpClientHandler.AutomaticDecompression = DecompressionMethods.All;
HttpClient httpClient = new HttpClient(httpClientHandler);
var api = new CepApi(httpClient, httpClientHandler);

Caso queira usar o HttpClient e não tiver acesso ao handler (por exemplo, em um contexto DI no Asp.net Core onde esitver usando o IHttpClientFactory):

HttpClient yourHttpClient = new HttpClient();
var api = new CepApi(yourHttpClient);

Você perderá algumas configurações, por exemplo: Setar e obter Cookies, Client Certificates, Proxy settings. Você precisará gerenciar isso manualmente no setup do seu HttpClient, caso contrário esses recursos não estarão disponíveis.

Segue um exemplo de setup do DI em um projeto web:

services.AddHttpClient<CepApi>(httpClient => new CepApi(httpClient)
  .ConfigurePrimaryHttpMessageHandler(config => new HttpClientHandler
    {
       AutomaticDecompression = DecompressionMethods.All
    });

Uso opcional de proxy​

Para usar o client da API com um proxy HTTP, configure um System.Net.WebProxy

Configuration c = new Configuration();
System.Net.WebProxy webProxy = new System.Net.WebProxy("http://myProxyUrl:80/");
webProxy.Credentials = System.Net.CredentialCache.DefaultCredentials;
c.Proxy = webProxy;

Exemplo 1​

using System.Collections.Generic;
using System.Diagnostics;
using System.Net.Http;
using NuvemFiscal.Sdk.Api;
using NuvemFiscal.Sdk.Client;
using NuvemFiscal.Sdk.Model;

namespace Example
{
    public class Example
    {
        public static void Main()
        {

            Configuration config = new Configuration();
            // Configure OAuth2 access token for authorization: oauth2
            config.AccessToken = "YOUR_ACCESS_TOKEN";

            // cria instâncias de HttpClient, HttpClientHandler para serem reutilizadas em qualquer Api
            HttpClient httpClient = new HttpClient();
            HttpClientHandler httpClientHandler = new HttpClientHandler();
            var apiInstance = new CepApi(httpClient, config, httpClientHandler);
            var cep = "cep_example";  // string | CEP sem máscara.

            try
            {
                // Consultar endereço através do CEP
                CepEndereco result = apiInstance.ConsultarCep(cep);
                Debug.WriteLine(result);
            }
            catch (ApiException e)
            {
                Debug.Print("Erro ao chamar CepApi.ConsultarCep: " + e.Message );
                Debug.Print("Status Code: "+ e.ErrorCode);
                Debug.Print(e.StackTrace);
            }

        }
    }
}

Exemplo 2​

using IdentityModel.Client;
using NuvemFiscal.Sdk.Client;
using NuvemFiscal.Sdk.Api;
using NuvemFiscal.Sdk.Model;

// Cria o HttpClient para uso nas requisições
var httpClient = new HttpClient();
var httpClientHandler = new HttpClientHandler();

// Obtém o access token a partir das credenciais
var tokenResponse = await httpClient.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest
    {
        Address = "https://auth.nuvemfiscal.com.br/oauth/token",
        ClientId = Environment.GetEnvironmentVariable("NUVEMFISCAL_CLIENTID"),
        ClientSecret = Environment.GetEnvironmentVariable("NUVEMFISCAL_CLIENTSECRET"),
        Scope = "empresa cep"
    }
);
if (tokenResponse.IsError) throw new Exception(String.Format("{0}: {1}", tokenResponse.Error, tokenResponse.ErrorDescription));

// Cria a configuração com o Access Token
var config = new Configuration
{
    AccessToken = tokenResponse.AccessToken
};

// Cria a API de CEP e faz a consulta
var cepApi = new CepApi(httpClient, config, httpClientHandler);
var cepResult = cepApi.ConsultarCep("80030030");
Console.WriteLine(cepResult);

// Cria a API de empresa e faz upload the um certificado para uma empresa 
// que já está previamente cadastrada
var empresaApi = new EmpresaApi(httpClient, config, httpClientHandler);
var empresa = new Empresa();
var pedidoCadastro = new EmpresaPedidoCadastroCertificado
{
    certificado = File.ReadAllBytes("C:\dados\meucertificado.pfx"),
    password = "123"
};

// Cadastra o certificado
var resposta = empresaApi.CadastrarCertificadoEmpresa("46363985000110", pedidoCadastro);

Referência completa​

O repositório do GitHub contém a lista de todos os endpoints e métodos correspondentes, classes DTOs, parâmetros, e mais. Visite o repositório para uma referência completa do SDK para .NET: