Pular para o conteúdo principal

Autenticação

Todas as requisições à API deve ser autenticadas através do envio de um header HTTP Authorization com o valor Bearer <token>, onde <token> é o token de acesso à API (access token).

A Nuvem Fiscal suporta o padrão OAuth 2 (fluxo client_credentials) para a obtenção do token de acesso, e os passos necessários para isso são descritos a seguir.

Criação das credenciais​

Você deve navegar para o Console da Nuvem Fiscal para a obtenção das suas credenciais.

info

O acesso ao console requer que você esteja logado na Nuvem Fiscal. Caso contrário você sera redirecionado a uma tela de login onde também poderá criar gratuitamente uma nova conta caso não tenha uma.

No console, a seção Credenciais de API lista todas as credenciais que você criou previamente. Para criar uma nova credencial, clique no botão Criar credencial.

tip

O uso do console, incluindo a criação de credenciais, requer que sua conta tenha um plano ativo. Se você não possuir um, você será redirecionado para uma tela de seleção de plano. Não se preocupe, você pode começar com nosso Plano Grátis com amplos recursos e limites e, se necessário, posteriormente migrar para qualquer um de nossos planos disponíveis.

Na tela para criação de nova credencial, escolha o tipo de credencial:

Recomendamos começar usando a API de sandbox. Assim que sua integração estiver implementada e validada, você pode migrar para a API de produção.

Clique em Confirmar para gerar as credenciais. Uma nova tela será mostrada informando os valores do Client ID e do Client Secret. Anote esses valores, ou clique no botão Baixar credencial pra fazer o download the um arquivo CSV contendo as credenciais.

info

O Client Secret só é mostrado uma vez, nessa tela. Anote ou faça o download das credenciais. Se você não souber mais o Client Secret, você não poderá mais restaurá-lo e não poderá mais usar as credenciais do respectivo Client ID. Não se preocupe, você sempre pode criar novas credenciais, mas um outro Client ID será gerado.

danger

Mantenha o Client ID e principalmente o Client Secret em lugar seguro. Nunca inclua o Client Secret em arquivos texto ou de código-fonte, principalmente se incluídos em sistemas de versionamento de código-fonte como Git ou SVN. Evite usar o Client Secret em aplicações não seguras (mobile, desktop, web). O portador das credenciais terá acesso à API e poderá emitir ou excluir documentos fiscais.

Com as credenciais criadas (Client ID e Client Secret), você pode obter o token de acesso à API.

Obtendo o token de acesso​

O token de acesso pode ser obtido através de uma requisição padrão OAuth 2 à URL de token, usando o fluxo client_credencials. A requisição deve ser construída da seguinte forma:

  • A URL para obtenção do token: https://auth.nuvemfiscal.com.br/oauth/token
  • Use o método HTTP POST
  • O header Content-Type deve ser application/x-www-form-urlencoded
  • O corpo da requisição deve conter os parâmetros client_id, client_secret, grant_type e scope, no formato nome=valor, separados por & e codificados com percent-encoding.
  • O parâmetro grant_type deve conter o valor client_credentials.
  • Os parâmetros client_id e client_secret devem conter, respectivamente, os valores das credenciais Client ID e Client Secret obtidos no console da Nuvem Fiscal.
  • O parâmetro scope deve conter as "permissões do token de acesso", separados por espaços (lembrando que ao usar o percent encoding o espaço torna-se %20. Cada serviço possui escopos respectivos. Alguns exemplos são empresa, cep, cnpj, nfe, nfce, nfse, cte e mdfe.

Exemplo de requisição para obtenção de token

A requisição HTTP a seguir obtém o token de acesso usando um Client ID de valor acbdef, um Client Secret de valor 123456 e o escopo cep cnpj nfse. Obviamente, ao fazer a sua requisição use os seu respectivo Client ID e Client Secret:

POST https//auth.nuvemfiscal.com.br/nuvemfiscal/oauth/token HTTP/1.1
Host: auth.nuvemfiscal.com.br
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=abcdef&client_secret=123456&scope=cep%20cnpj%20nfse

Se a requisição estiver correta e as credenciais válidas, a requisição retornará com código de status 200 (sucesso) e o corpo da resposta conterá um JSON similar ao seguinte:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiIw...",
    "token_type": "bearer",
    "scope": "cep cnpj nfse",
    "expires_in": 2592000
}

A propriedade access_token é a mais importante e contém o token de acesso (que em uma resposta real é bem mais longo do que o mostrado no exemplo). É esse valor que você deve usar para fazer as requisições autenticadas.

As propriedades bearer e scope são informativas, a última indica para quais escopos o token é válido.

A propriedade expires_in é relevante e indica em quantos segundos o token irá expirar, contados a partir do momento da emissão do token. Após esse tempo, o token ficará inválido e você deverá requisitar outro para ter acesso à API.

Atenção

Recomendamos que a renovação do token de acesso seja feita próximo de sua expiração para evitar bloqueio por excesso de requisições ao servidor de autorização.

Para mais informações, consulte limites de requisição.

Fazendo requisições autenticadas à API​

Uma vez de posse do token de acesso, você pode fazer requisições autenticadas à API da Nuvem Fiscal. Para isso basta criar a sua requisição HTTP à API normalmente, e adicionar o header Authorization, com valor Bearer seguido do token (atenção ao espaço entre o texto Bearer e o token).

O exemplo a seguir faz uma requisiçào autenticada à API de CEP usando o token de acesso obtido no passo anterior:

GET https://api.nuvemfiscal.com.br/cep/04094000 HTTP/1.1
Host: api.nuvemfiscal.com.br
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiOiIw...
Accept: */*

Se você chegou até aqui efetuando com sucesso uma requisição à API, você está apto a fazer qualquer outra requisição, a Nuvem Fiscal completa está ao seu alcance! Você pode emitir documentos fiscais, realizar consultas, efetuar cancelamento dos documentos, fazer download do XML, entre outras operações.

Consulte a referência completa da API Nuvem Fiscal para conhecer todos os serviços disponíveis seus respetivos endpoints e como usá-los.