Autenticações

Informações Gerais

Nesta página estão descritos os modelos de autenticação utilizados pelo Emissor Fiscal.
Esses modelos definem como a automação se autentica para consumir APIs e funcionalidades do Emissor Fiscal.

Para NFS‑e, não há autenticação por chamada — a emissão é habilitada por cadastro do emissor.

Versões de Autenticação disponíveis

Autenticação V1 - Usuário e Senha
Autenticação V2 - Chave de Integração
Autenticação V3 - Chave de Integração com Chave Master
- Autenticação da Solução
- Criação de Chave de Acesso para Emissor
- Autenticação do Emissor
Autenticação NFS-e

Autenticação V1 - Usuário e Senha

É possível utilizar de duas formas a autenticação V1, conforme detalhe a seguir:

Autenticação no Client 2.0

O componente Client 2.0 só aceita autenticação utilizando usuário e senha.

O usuário e senha do Client 2.0 são disponibilizados via e-mail no momento do cadastro da empresa, no endereço de email indicado do campo email do responsável técnico.
A gestão do usuário client também pode ser feita via Plataforma TecFiscal.

Autenticação das APIs - Integração Direta

Para utilizar as funcionalidades que estão disponíveis apenas via Integração Direta (APIs) do Emissor Fiscal utilizando o usuário e senha do Client 2.0 a automação deve seguir a seguinte orientação:

Passo 1. Requisição de chave pública de encriptação

Em nosso ambiente foi disponibilizado uma rota para distribuição de uma chave.

Método	Rota
GET	{HostApiCompanyManager}:{PortApiCompanyManager}/services/getpublickey

Ambientes:

Ambiente	URL
HML	https://api-hml.fiscalpartners.com.br/services/getpublickey
PRD	https://api.fiscalpartners.com.br/services/getpublickey

Essa chave pública é estável e só muda caso a chave privada seja alterada.

Passo 2. Encriptação dos dados de requisição

Para encriptação de seus dados será necessário a importação do algoritmo RSA de sua linguagem e o corpo a ser encriptado deve seguir o seguinte Json:

{ "UserName": "{ username }", "Password": "{ password }" }

No qual:

{publicKey} = chave recebida da requisição anterior
{data} = Json gerado pelos seus dados de autenticação

Exemplo em C#:

var rsa = RSA.Create(2048);
rsa.ImportRSAPublicKey(publicKey, out _);
var encryptedDataBytes = rsa.Encrypt(data, RSAEncryptionPadding.OaepSHA256);
return encryptedDataBytes;

Passo 3. Requisição de autenticação

Para sua autenticação, envie o valor gerado pelo algoritmo de encriptação para a rota a seguir, com o corpo de requisição no seguinte formato da tabela:

Método	Rota	Parâmetros
POST	`{{AuthenticationHost}}:{{AuthenticationHostPort}}/auth/authentication`	`{{ AuthenticationPayload}}:{{encrypted}}`

| HML | https://api-hml.fiscalpartners.com.br/auth/authentication | | PRD | https://api.fiscalpartners.com.br/auth/authentication |

Abaixo temos o exemplo do retorno

{
"AuthenticateJsonResult": 
[
    {
        "Key": 1, 
        "Value": 3020051f-7dc2XXXXXXXXX...01"
    },
    {
        "Key": 2,
        "Value": "mchh0NqswkKK0/4y82MEU4yCqrxxxxxxx...LWf3k="
    }
    {   
        "Key": 3, 
        "Value": 89f3175aXXXXXXXXX...aa2"
    }
    {
        "Key": 4, 
        "Value": f09bbc01-XXXXXXXXX...45c576"
    }
]
}

Com esses dados deve-se montar o cabeçalho da mensagem para consumo das APIs, que contém os seguintes campos:

Content-Type: application/json
CurrentCompany: valor KEY 1
AuthorizationToken: Valor KEY 2
CurrentUser: Valor KEY 3
AccessGroup: Valor KEY 4
Application: DE02E733-A636-4C41-907F-55C8721FCCDF

⚠️Controle de Consumo Indevido: Adicionado controle de 10 requisições por minuto para o ambiente de HML na autenticação para uma mesma origem.

Autenticação V2 - Chave de Integração

Essa autenticação oferece maior controle de acesso e flexibilidade na liberação de funcionalidades via Integração Direta.

Criação de Chave de Integração

Criar uma chave de integração:

Passo 1. Acessar menu Configurações / Contas de Serviço na Plataforma TecFiscal e clicar em Nova Chave

Passo 2. Selecionar o projeto Integração Emissor Fiscal, definir nome e descrição para a chave de integração que está sendo criada

Passo 3. Clicar em Vincular e selecionar o nível de alcance da chave que está sendo criada. As opções são:

Grupo Econômico: o alcance da chave criada será limitado ao grupo econômico informado;
Solução: o alcance da chave criada se estenderá a todos os CNPJs que estão vinculados a Solução.

Passo 4. Salvar e ir até a opção Chave para copiar a chave criada.

A gestão das chaves de integração é feita nesta mesma tela.

Necessário autenticar na API enviando a chave de integração passada gerada na Plataforma TecFiscal. Lembrando que essa chave será diferente para ambiente de Homologação e Produção e será liberada para grupos econômicos específicos, podendo ter mais de uma chave ativa.

Autenticação com Chave de Integração

Endpoint HML: https://api-portal-auth-hml.fiscalpartners.equals.com.br/ContaServico/Autenticacao/Login

Endpoint PRD: https://api-portal-auth.fiscalpartners.equals.com.br/ContaServico/Autenticacao/Login

Método: POST

Chave = chave de integração criada no tópico anterior.

Exemplo de envio:

{
    "Input": 
    {
    "Chave": "string"
    }
}

Exemplo de Retorno:

{
 
"Token": "string",
 
"ExpiraEm": "string"
 
}

Autenticação V3 - Chave de Integração com Chave Master

Atualmente este formato de autenticação é de uso exclusivo do Client em Nuvem e é composto por 3 etapas, a saber: processo de autenticação da solução, processo de criação de chave de acesso para emissor, e processo de autenticação do emissor.

Autenticação da Solução

Para acessar as funcionalidades que requerem maior privilégio, a autenticação deve ser feita a nível de solução. Para isso, é necessário autenticar utilizando a chave Master, conforme segue:

Passo 1. Solução parceira gerar a Chave Master, acessando a Plataforma TecFiscal em Gestão de Chaves de Integração e selecionar o projeto Client em Nuvem.

Passo 2. Obter uma chave pública através da URL /Authenticate/GetPublicKey

Passo 3. Encriptar a chave de acesso master (Key) utilizando a chave pública do Client em Nuvem. Para encriptar, utilize o algoritmo de criptografia RSA (tamanho de chave 2048).

Passo 4. Enviar a chave de acesso master (Key) encriptada no formato base64 na tag key para realizar o login da Solução na API de Autenticação do Client em Nuvem.

Passo 5. Realizar a autenticação com a chave master através da URL /Authenticate/MasterLogin para obter o token de autorização, conforme exemplo abaixo:

{
   "key": "string",
   "solutionId": 123
}

Em caso de sucesso será retornado o Token que dará acesso as APIs do Client em Nuvem que exigem esse nível de acesso, além do tempo de expiração do token em segundos.

Criação de Chave de Acesso do Emissor

Cada cliente emissor terá sua chave de acesso (Key) individual que será utilizada no momento da autenticação.

A segurança da comunicação é baseada em dois conceitos principais:

Chave Master: É o segredo primário, habilitado pelo time de RC, que identifica a Solução. Esta chave é utilizada no fluxo de MasterLogin para gerar o Token de Autorização e para criar as chaves individuais dos Emissores. A Chave Master deve ser tratada como um segredo de alta segurança.
Token de Autorização (JWT): É a credencial temporária, gerada após a autenticação (login) com a Chave Master ou com a chave do Emissor (login do Emissor). Este Token é o que deve ser enviado no header Authorization para acessar as demais APIs do Client em Nuvem do Emissor Fiscal.

Cada cliente emissor terá sua chave de acesso (Key) individual que será utilizada no momento da autenticação. Para criar essa chave é necessário seguir os seguintes passos:

Alerta de desenvolvimento: A criação da chave de acesso do Emissor (Passos 1 a 8) requer a implementação de algoritmos de criptografia RSA 2048 para encriptar a chave master e descriptografar a chave do emissor retornada.

Passo 1. Solução deve possuir uma chave master habilitada, em caso de dúvidas, nosso time de RC poderá apoiar no processo de obtenção da chave master. Com esta chave em mãos, vamos para os próximos passos.

Passo 2. Obter uma chave pública através da URL /Authenticate/GetPublicKey

Passo 3. Encriptar a chave de acesso master (chave aberta com até 80 caracteres) utilizando a chave pública do Emissor Fiscal. Para encriptar, utilize o algoritmo de criptografia RSA (tamanho de chave 2048).

Passo 4. Enviar a chave de acesso master (Key) encriptada no formato base64 na tag key para realizar o login na API de Autenticação do Client em Nuvem.

Passo 5. Realizar a autenticação com a chave master através da URL /Authenticate/MasterLogin para obter o token de autorização, conforme exemplo abaixo:

{
   "key": "string",
   "solutionId": 123
}

Passo 6. Gerar um par de chaves RSA (tamanho de chave 2048 devendo ser exportada como PKCS1), onde a chave pública será utilizada para encriptar no Client em Nuvem a chave que será retornada para o emissor.

Passo 7. Realizar a requisição para criar a chave do emissor contendo no corpo os seguintes campos: cnpj e publicKey (obtida no passo anterior em base64). Esta requisição deve ser enviada para a URL: /Authenticate/CreateEmissorKey. Além disso, a requisição deve incluir os seguintes cabeçalhos:

Content-Type: application/json
Authorization: Token gerado a partir do login com a chave de acesso master.

O corpo da requisição deve ser enviado no formato JSON, conforme exemplo abaixo:

{
 "Cnpj": "32048439000180",
 "PublicKey": "{{PublicKey}}"
 "solutionId":""
}

Exemplo de retorno:

{
"emissorKey":"QXF1aV9vX3JldG9ybm9fZGasdasdasJpYWRhX2NvbV9zdWNlc3NvX3BhcmFfdW1fY25sjdalsdjalkjG8=",
"expiresIn": 2592000
}

Sendo o conteúdo de EmissorKey a chave criada e ExpiresIn o tempo de expiração da chave em segundos.

Passo 8. Descriptografar o retorno da tag “emissorKey” através da chave privada RSA gerada anteriormente, obtendo assim a chave de acesso (Key) do emissor.

⚠️ Importante: Somente uma chave do emissor será mantida ativa, ou seja, caso seja gerada uma nova chave a anterior será revogada automaticamente!

Guarde essa chave com segurança!

Autenticação do Emissor

Os emissores que já possuem a chave de acesso (Key) individual devem realizar a autenticação para obter o token de autorização de acesso às APIs do Client em Nuvem seguindo os passos abaixo detalhados.

Por questão de segurança, orientamos que a chave de acesso (Key) deve ser encriptada para realização da autenticação.

Passo 1. Obter Chave Pública na URL /Authenticate/GetPublicKey

Passo 2. Encriptar a chave de acesso (Key) utilizando a chave pública do Client em Nuvem, por meio do algoritmo de criptografia RSA (tamanho de chave 2048)

Passo 3. Enviar a chave de acesso (Key) encriptada em formato base64 na tag key para realizar o login do emissor na API de Autenticação do Client em Nuvem

Passo 4. Realizar autenticação do emissor na API /Authenticate/EmitLogin, informando o CNPJ e a chave de acesso da empresa de forma encriptada, conforme exemplo abaixo:

{
  "Cnpj": "50354031000119",
  "Key": "{{EmissorKeyBase64}}",
  "SolutionId": 37
}

Em caso de sucesso será retornado o Token que dará acesso as demais APIs do Client em Nuvem, além do tempo de expiração do token em segundos.

Possíveis retornos HTTP

200 - OK
400 – Ocorreu um problema na requisição
401 - Sem Autorização
429 – Muitas Solicitações
500 – Erro Interno do Servidor
503 - Serviço Indisponível

Autenticação NFS-e

No fluxo de emissão de NFS‑e, não há autenticação realizada pelo Emissor Fiscal.

A liberação para emissão ocorre a partir do cadastro do emissor.

Após habilitado, o Emissor Fiscal apenas realiza o envio e o acompanhamento das mensagens de NFS‑e, sem validação de credenciais ou geração de tokens.

Por esse motivo, no contexto de NFS‑e, a atenção do integrador deve estar no correto cadastro do emissor e na homologação do fluxo, e não na configuração de autenticação.

Glossário

Emissor

CNPJ habilitado no Emissor Fiscal para emissão de documentos fiscais.

Solução

Sistema ou automação responsável por integrar-se ao Emissor Fiscal para emissão de documentos fiscais.

O termo “Solução” refere-se à aplicação que consome as interfaces do Emissor Fiscal e gerencia os emissores, não caracterizando uma parceria comercial.

Automação

Aplicação desenvolvida por terceiros que realiza a integração técnica com o Emissor Fiscal.

Este conteúdo foi útil para você?

Autenticação V1 - Usuário e Senha​

Autenticação V2 - Chave de Integração​

Autenticação V3 - Chave de Integração com Chave Master​

Glossário​

Autenticação V1 - Usuário e Senha

Autenticação V2 - Chave de Integração

Autenticação V3 - Chave de Integração com Chave Master

Glossário