O PlugNotas da Tecnospeed é uma API Rest que facilita a integração de documentos fiscais como NFSe e NFSe Nacional, NFe, NFCe, MDFe e CFe por meio de uma arquivo JSON estruturado para cada documento. O PlugNotas é a escolha perfeita para quem busca uma API para integrar ao seu sistema WEB com requisições em HTTPS, sem se preocupar com as atualizações das diversas NTs publicadas pela SEFAZ.
Neste artigo você encontrará todas as informações para começar sua integração ou testar o PlugNotas:
- Criando acesso a interface web
- Ambientes de envio disponíveis
- Cadastrando Certificados e Empresas via API
- Cadastrando Certificados e Empresas via Interface
- Fluxo de emissão do Plugnotas
- Fluxo utilizando a consulta
- Fluxo utilizando o WebHook
- Envio de documentos utilizando o Postman
Como criar o meu primeiro acesso a nova interface do PlugNotas?
A nossa interface hoje serve como um acelerador, para clientes que contratam com prazos apertados, podendo depositar a maior parte de nossos esforços na integração das notas, usando a Interface para agilizar essa parte do cadastro da empresa, cadastro de certificados e visualização de suas notas fiscais.
A nova interface do PlugNotas vai fornecer mais algumas funções de ajuda, como painel para monitorar notas e criação de novos usuários. Portanto, vamos agora mostrar como ter acesso a ela.
- Como inicia a minha integração com esta interface?
- Como criar novos usuários?
- Mas e meu token? Ele muda?
Conta TecnoSpeed
Atualmente, nossa interface utiliza os dados do TecnoAccount para realizar o login, o que permite realizarmos a verificação das licenças ativas do cliente. Com uma conta Tecnospeed você terá acesso rápido a configurações e ferramentas para gerenciar todos os produtos e serviços que a Tecnospeed oferece.
Como inicia a minha integração com esta interface?
Para o seu primeiro acesso, siga os passos abaixo:
1- Comece criando uma conta em: https://conta.tecnospeed.com.br/ . Ao abrir esse link, vá na opção "Crie a sua conta".
2- Os dados que serão inseridos devem ser o de sua Software House, aquela que já tem contrato ativo com o PlugNotas. Insira o mesmo cnpj utilizado ao fechar o seu contrato, para que possamos realizar a busca correta de seus dados.
ATENÇÃO: Se você já é cliente Tecnospeed e usa a interface atual (app.plugnotas.com.br), crie o cadastro usando EXATAMENTE o mesmo usuário e senha que você já utiliza atualmente. Depois que a conta for criada, quando acessar o PlugNotas, será possível criar outros usuários a partir deste.
3- Realize a ativação de sua conta por meio de um e-mail recebido;
4- Agora você já poderá logar no PlugNotas com os mesmos dados utilizados para logar em https://conta.tecnospeed.com.br/ . Caso desejar realizar a alteração do e-mail principal ou senha de acesso ao PlugNotas, será necessário alterar diretamente em https://conta.tecnospeed.com.br/
Localizando o token
O Token que será utilizado para as emissões nos ambientes de homologação e produção são localizados na GUI do PlugNotas, ao clicar no avatar no canto superior direito da interface, é apresentado a opção de token, ao qual está contido o token que vocês utilizarão na integração:
Observação: O token é único por software house.
Como criar novos usuários?
Como comentado mais acima, é possível realizar o cadastro de usuários adicionais para acessarem a interface. Você pode cadastrar o usuário com perfil cliente (empresa emissora de notas), desenvolvedor (dev responsável pela parte técnica) e administradores (usuário da Software House responsável para segundo acesso). A Software House poderá vincular empresas a um único usuário ou poderá vincular um grupo de empresas para estabelecer permissões como um todo, conforme veremos abaixo.
A Software House tem a possibilidade de estabelecer permissões e limitar acessos para cada usuário cadastrado, como por exemplo:
Para mais detalhes sobre agrupamento de usuários, acesse aqui.
Mas e meu token? Ele muda?
Não, o seu token permanece o mesmo!
A interface muda e mesmo que use outros usuários, o token ainda é o mesmo que você usa atualmente, o que significa que você NÃO VAI PRECISAR ATUALIZAR O TOKEN NA SUA APLICAÇÃO.
O caminho para obter o token, permanece o mesmo caminho da interface anterior: Ao acessar, vá no seu avatar no canto superior direito da tela > Clique em "Exibir token"
Obs: o TecnoAccount vai te fornecer um token também, mas NÃO vai ser ele que você usará para o PlugNotas. O Plug vai ter um token só dele.
Ambientes de envio disponíveis no PlugNotas
SandBox:
ambiente disponibilizado para testes da API, os retornos desse endpoint são mockados, pode ser utilizado para validar principalmente a estrutura dos envios e dos retornos que vocês terão e também os cadastros de empresa e certificado, já que os cadastros de empresa e certificado não podem ser excluídos em produção.
A API é um mock, ou seja, todas as requisições morrem nos nossos servidores e os retornos são sempre fixos. Nenhuma requisição enviada aqui vai para os servidores das Prefeituras/SEFAZ.
As rotas de cadastro de certificado e de empresa, trazem o retorno exato do que você está enviando. As rotas que envolvem as notas (envio, cancelamento e impressão), sempre retornam as mesmas informações mockadas.
Para este ambiente devem ser utilizados o token e endpoints próprios.
Os endpoints sempre estarão a direita da documentação da requisição em https://docs.plugnotas.com.br/:
E o token do ambiente de Sandbox sempre será este: 2da392a6-79d2-4304-a8b7-959572c7e44d
Também temos as collections de testes já prontas para importação no postman:
https://www.getpostman.com/collections/9eaafab3bddfa5ac8074
Envios em produção e homologação
Os envios em produção e em homologação são no ambiente ao qual chamamos de API oficial, que possui comunicação direta com a prefeitura/SEFAZ, eles compartilham do mesmo endpoints e token(gerado no passo anterior).
Homologação:
Para emitir em homologação, é necessário que o atributo config.producao esteja setado como FALSE.
"config":
{
"producao": false,
}
Em Produção:
Esse mesmo atributo config.producao tem que estar como TRUE.
"config":
{
"producao": true,
}
Pela interface também é possível configurar o ambiente de emissão, ao editar a empresa:
Exemplo NFSe, mas se aplica para os demais documentos também.
Cadastrando Certificados via API
Para realizar a emissão dos documentos fiscais com o Plug Notas os emissores/prestadores precisam estar cadastrados na nossa API. Esse cadastro pode ser realizado pelo portal APP2 ou usando a rota da API.
Apenas certificados do modelo A1 funcionando com o PlugNotas, com extensão .PFX ou .P12.
Exemplo da requisição do método POST usando o postman preenchimento do HEADERS.
POST
https://api.plugnotas.com.br/certificado
Na imagem acima temos o preenchimento do headers, onde deve informar o x-api-key (preenche o campo com o token da software house).
Sa sequência preenchimento do BODY onde deve informar o tipo form-data com os parâmetros senha e arquivo.
Headers
Nome | Descrição | Exemplo |
x-api-key | Token de autenticação da SoftwareHouse (vide primeiro passo) | 2da392a6-79d2-4304-a8b7-959572c7e44d |
Body
Nome | Descrição |
arquivo | Certificado digital enviado como binário (obrigatório) |
senha | Senha de instalação do certificado digital (obrigatório) |
E-mail para notificações como vencimento do certificado (opcional) |
Retorno
Exemplo de retorno (Status code 200):
{
}
Exemplo de retorno com erro (Status code 400):
{
"error": {
"message": "A senha utilizada na tentativa de upload do Certificado está incorreta.",
"data": {
"senha": "xxxx"
}
}
}
Vai vir Status code 400 ou 401
Caso queira saber mais sobre essa rota, clique aqui.
Cadastrando Empresas via Api
A empresa cadastrada aqui é a que sairá como emitente/prestador na nota fiscal. Então se você contratou o PlugNotas para integrar no seu sistema e vender isso, você irá cadastrar o seu cliente aqui. Se você contratou para integrar no seu sistema interno e emitir as suas próprias notas, você irá cadastrar o seu próprio CNPJ aqui.
POST
https://api.plugnotas.com.br/empresa
Para cadastrar usando a API monte sua requisição do tipo POST, exemplo abaixo:
Headers
Nome | Descrição | Exemplo |
x-api-key | Token de autenticação da SoftwareHouse (vide primeiro passo) | 2da392a6-79d2-4304-a8b7-959572c7e44d |
Content-Type | Indica o tipo de arquivo | application/json |
Body
Exemplo de arquivo de envio:
{
"cpfCnpj":"29062609000177",
"inscricaoMunicipal":"8214100099",
"inscricaoEstadual":"1234567850",
"razaoSocial":"Tecnospeed S/A",
"nomeFantasia":"Tecnospeed",
"certificado":"5af59d271f6e8f409178fbf3",
"simplesNacional":true,
"regimeTributario":1,
"incentivoFiscal":true,
"incentivadorCultural":true,
"regimeTributarioEspecial":5,
"endereco":{
"tipoLogradouro":"Avenida",
"logradouro":"Duque de Caxias",
"numero":"882",
"complemento":"17 andar",
"tipoBairro":"Zona",
"bairro":"Zona 01",
"codigoPais":"1058",
"descricaoPais":"Brasil",
"codigoCidade":"4115200",
"descricaoCidade":"Maringá",
"estado":"PR",
"cep":"87020-025"
},
"telefone":{
"ddd":"44",
"numero":"3037-9500"
},
"email":"empresa@plugnotas.com.br",
"nfse":{
"ativo":true,
"tipoContrato":0,
"config":{
"producao":true,
"rps":{
"serie":"RPS",
"numero":1,
"lote":1
},
"prefeitura":{
"login":"teste",
"senha":"teste123"
},
"email":{
"envio":true
}
}
},
"nfe":{
"ativo":true,
"tipoContrato":0,
"config":{
"producao":true,
"impressaoFcp":true,
"impressaoPartilha":true,
"serie":1,
"numero":1,
"dfe":{
"ativo":true
},
"email":{
"envio":true
}
}
},
"nfce":{
"ativo":true,
"tipoContrato":0,
"config":{
"producao":true,
"serie":1,
"numero":1,
"email":{
"envio":true
},
"sefaz":{
"idCodigoSegurancaContribuinte":"string",
"codigoSegurancaContribuinte":"string"
}
}
}
}
*Obs: a descrição dos campos do json estão descritas na documentação complementar no fim desse artigo
Exemplo
Retorno
Exemplo de retorno (Status code 200):
{
"message": "Cadastro efetuado com sucesso",
"data": {
"cnpj": "23995875000176"
}
}
Exemplo de retorno com erro (Status code 400):
{
"error": {
"message": "Falha na validação do JSON de Empresa",
"data": {
"fields": {
"certificado": "Preenchimento obrigatório"
}
}
}
}
Vai vir Status code 400, 401 ou 409
Veja mais detalhes na documentação da rota Cadastrar empresa.
Cadastrando Certificados pela Interface
O certificado aceito hoje é apenas o do modelo A1.
Ao realizar o login na interface, vá até o menu do lado esquerdo e clique em Certificado. Lá ficarão visíveis os certificados depois de cadastrados. Clique em Novo e na tela que aparecer, preencha a senha do certificado e faça o upload do arquivo. Pode ser arrastando ele para a tela ou clicando ali e abrindo a caixa de seleção.
O campo de e-mail presente nessa tela, será usado para que enviemos notificações, como a de certificado vencido, por exemplo.
O GIF abaixo ilustra esse caminho:
Cadastrando Empresas pela Interface
A empresa cadastrada aqui é a que sairá como emitente/prestador na nota fiscal. Então se você contratou o PlugNotas para integrar no seu sistema e vender isso, você vai cadastrar o seu cliente aqui. Se você contratou para integrar no seu sistema interno e emitir as suas próprias notas, você vai cadastrar o seu próprio CNPJ aqui.
Acesse o menu Empresas, presente ao lado esquerdo. Seguindo a mesma lógica dos certificados, aqui ficarão as empresas que forem cadastradas. Clique em Novo e então aparecerá o formulário de cadastros. Alguns campos aparecerão apenas quando um documento em específico for marcado.
O GIF mostra o caminho e a tela.
Fluxo de emissão do PlugNotas
Os envios de notas são realizados de forma assíncrona, o que significa que o retorno direto do seu envio, NÃO é informando se a nota está autorizada ou não. Para isso, será necessário o uso de consultas dessas notas ou o uso do webhook para receber notificações. Nessa documentação, ambos os fluxos estão explicados.
Nesse fluxo, vamos assumir que os passos anteriores já foram realizados, como todos os cadastros, configurações da empresa e informações dentro do json.
Fluxo utilizando a consulta
O fluxo se inicia com o envio do arquivo json via API para o PlugNotas. Quando chega ali, nós vamos buscar os dados do cadastro da empresa, setar a numeração da nota, realizar os cálculos de impostos e valores (caso eles não constem no json) e montar o XML para enviar isso tudo para a SEFAZ. Ao mesmo tempo em que todo esse processo é feito, a API já retornou para você o ID dessa nota dentro do nosso banco de dados.
A SEFAZ vai processar essa nota e retornar para nós. Para que você consiga saber o resultado do processamento ou se ela ainda permance em processamento, você deve utilizar a rota de consulta de notas usando como filtro o ID retornado da rota de envio.
O retorno da consulta vai dizer se a nota foi autorizada (CONCLUÍDO), rejeitada (REJEITADO) ou se ainda está pendente de processamento (PROCESSANDO).
Em caso de autorização, o processo por si só está finalizado, mas caso seja do seu interesse ou do seu cliente, você pode solicitar o PDF e/ou o XML dessa nota para o PlugNotas.
Em caso de rejeição, você deve analisar o motivo da rejeição e aplicar a correção, gerando um novo envio depois disso.
Em caso de processamento pendente, resta apenas aguardar e realizar novas consultas periódicamente para saber se o processo foi finalizado.
Fluxo utilizando o WebHook
WebHook pode ser cadastrado para a sua softwarehouse e você faz o rateio para os seus clientes, ou você pode criar um WebHook para cada cliente seu, um por CNPJ.
Para entender melhor esse ponto, essa documentação aqui tem todos os detalhes para que você possa compreender como realizar o cadastro desse WebHook, bem como informações de quantidades de tentativas e como os retornos chegarão até você.
Os retornos que vão te notificar ali, são:
CONCLUIDO
Este status informa que a nota foi processada e esta com status final de Autorizada.
CANCELADO
Este status informa que a nota consultada esta com status final de Cancelada.
Este status informa que as informações enviadas no JSON foram processadas pela API e rejeitada por algum motivo. Essa rejeição pode ter sido por um erro nas informações enviadas (parou na validação da API), ou rejeitada pela própria prefeitura. Caso o motivo da rejeição não esteja claro para você*, é necessário entrar em contato com a consultoria para análise da motivação da Rejeição e tratamento para o reenvio.
Para esse fluxo é primordial que se realize as configurações do WebHook para o qual enviaremos as notificações.
INTERROMPIDO
Este status é retornado quando a emissão é interrompida pela interface do plugNotas. Este status representa que o fluxo de emissão da NFSe foi pardo e ela não fará novas tentativas de comunicação.
O fluxo se inicia com o envio do arquivo json via API para o PlugNotas. Quando chega ali, nós vamos buscar os dados do cadastro da empresa, setar a numeração da nota, realizar os cálculos de impostos e valores (caso eles não constem no json) e montar o XML para enviar isso tudo para a SEFAZ. Ao mesmo tempo em que todo esse processo é feito, a API já retornou para você o ID dessa nota dentro do nosso banco de dados.
Notas pendentes de processamento não serão notificadas, apenas notas em estado final.
Envio dos documentos usando o postman.
O envio de nota é possível apenas pela API, pela rota:
POST https://api.plugnotas.com.br/{Documento}
E como arquivo de emissão, você utilizará o JSON de nota, dentro do body (raw)
Como response, você terá algo parecido com isto:
{
"documents": [
{
"idIntegracao": "XXXYY999",
"Emitente": "08187168000160",
"id": "5f1f7069af3fbe5296dfxxx"
}
],
"message": "Nota(as) em processamento",
"protocol": "0d09cf4b-6d94-42ed-8cf8-c687df91xxx"
}
É muito importante que este ID seja salvo, você o utilizará em várias requisições, e a equipe de consultoria sempre o solicita para o suporte.
Caso ocorra erro, o retorno será algo parecido com:
{
"error": {
"message": "Falha na validação do JSON de NFe",
"data": {
"fields": {
"documento[0].natureza": "Preenchimento obrigatório",
"documento[0].itens[0].ncm": "Preenchimento obrigatório",
}
}
}
}
Comentários
0 comentário
Por favor, entre para comentar.