1. Acesso à interface web
Para o seu primeiro acesso, siga os passos abaixo:
Comece criando uma conta em: https://conta.tecnospeed.com.br/ .
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 podermos realizar a busca correta de seus dados. Guarde bem os seus dados de login e senha, pois serão utilizados para o seu acesso ao PlugNotas.
Realize a ativação de sua conta;
Agora você já poderá logar no PlugNotas com os mesmos dados utilizados para logar em https://conta.tecnospeed.com.br/
URL da interface do PlugNotas: http://app2.plugnotas.com.br/
2. 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:
OBS.: O token é único por software house.
- Sandbox
3. Envios em Sandbox
O PlugNotas disponibiliza um ambiente mockado para testes ao qual pode ser utilizado para validar principalmente a estrutura dos envios e dos retornos que vocês terão e 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á mandando. As rotas que envolvem as notas (envio, cancelamento, impressão), sempre retornam as mesmas informações mockadas.
Para utilizar este ambiente, vocês irão dispor de alguns endpoints e um token 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 já prontas para importação no postman, para testes:
https://www.getpostman.com/collections/9eaafab3bddfa5ac8074
Obs.: Para testar em Sandbox com os seus dados, será necessário cadastrar o emitente por API.
- API OFICIAL
4. Cadastro de certificados
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.
O campo de e-mail presente nessa tela, será usado para enviarmos notificações, como a de certificado vencido, por exemplo.
O GIF abaixo ilustra esse caminho:
5. Cadastro de empresa
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ê cadastrará o seu cliente aqui. Se você contratou para integrar no seu sistema interno e emitir as suas próprias notas, você 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.
Os cadastros também podem ser realizados via API
6. Cadastro de certificado via API
Apenas certificados do modelo A1 funcionarão com o PlugNotas, com extensão .PFX ou .P12.
Para cadastrar o certificado será necessário utilizar a seguinte rota:
POST https://api.plugnotas.com.br/certificado
Com o BODY da seguinte forma:
multipart/form-data
7. 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 os endpoints e o token utilizado.
- Homologação:
Para emitir em homologação, é necessário que o atributo nfse.config.producao esteja setado como false.
Caso queira emitir em produção, o atributo nfse.config.producao tem que estar como true.
Pela interface também é possível configurar o ambiente de emissão, ao editar a empresa:
8. Envio
O envio de nota é possível apenas pela API, pela rota:
POST https://api.plugnotas.com.br/nfse
E como arquivo de emissão, você utilizará o JSON de nota, dentro do body (raw)
Como response, você terá algo parecido com isto:
É 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.
9. Consulta
Possuímos duas possibilidades de consulta: a consulta completa e a consulta resumida.
- Consulta completa:
É retornado um JSON com todas as informações da nota disponíveis (https://docs.plugnotas.com.br/#tag/NFSe/operation/get-nfse)
É utilizado o seguinte endpoint, em que o id da nota é utilizado como Path Parameter:
GET https://api.plugnotas.com.br/nfse/{idNota}
- Consulta resumida:
É retornado um json contendo apenas as informações mais relevantes (https://docs.plugnotas.com.br/#tag/NFSe/operation/nfseSummary)
É utilizado o seguinte endpoint, em que o id da nota é utilizado como Path Parameter:
GET https://api.plugnotas.com.br/nfse/consultar/{idNotaOrProtocol}
10. Como obter o XML
A rota para obter o XML disponibilizado pela prefeitura/SEFAZ é chamada no seguinte endpoint:
GET https://api.plugnotas.com.br/nfse/xml/{idNota}
É retornado exatamente o XML que a prefeitura retorna por webservice.
11. Como obter o PDF
A rota para obter o XML disponibilizado pela prefeitura/SEFAZ é chamada no seguinte endpoint:
GET https://api.plugnotas.com.br/nfse/pdf/{idNota}
12. Webhook
O PlugNotas possui a funcionalidade de webhook, ou seja, nós chamamos uma rota da sua API para trocarmos dados em tempo real, assim podemos notificar sua aplicação quando as notas terminarem seu processamento.
Possuímos duas configurações:
- Por organização:
Desta forma você irá criar uma única rota na sua aplicação, a qual será utilizada por nós para enviarmos todas as notificações de notas que finalizarem o processamento de todos os seus clientes.
- Por CNPJ:
Você irá criar e configurar uma rota para cada CNPJ emissor, ou seja, para cada prestador, e enviaremos as notificações diferentes para cada rota configurada dependendo do cnpj configurado.
O que eu preciso para utilizar a integração por webhook?
Em sua API, crie um endpoint (rota) que aceite uma requisição POST, PATCH, ou PUT.
Caso sua aplicação processe corretamente nossa mensagem (SUCESSO), essa rota precisa devolver um Status Code 200.
Em caso de falha do processamento de nossa mensagem (ERRO), essa rota precisa devolver um Status Code que não pertença à família do 2xx, como, por exemplo, um 500.
Cadastre seu endpoint em /webhook ou /empresa/{cnpj}/webhook.
Tentaremos reenviar a requisição para a sua API diversas vezes, em intervalos regulares, até que o limite de tentativas seja excedido (~ 6 horas), ou que sua API retorne um Status Code 2xx.
Cadastrando:
POST https://api.plugnotas.com.br/webhook
Exemplo:
Response:
{
"message": "Operação realizada com sucesso",
"data": {}
}
Após realizar esta configuração, a cada nota enviada, nós iremos consultá-la automaticamente de tempos em tempos, e quando ela chegar nos status finais de AUTORIZADA, CANCELADA, ou REJEITADA, nós enviamos uma notificação para o endpoint configurado, contendo o JSON resumido da nota:
Exemplo:
Estes são os principais fluxos e rotinas iniciais para a implantação da NFSe com o PlugNotas.
Caso necessite de mais auxílio, vocês possuem as seguintes formas:
- Chat e tickets:
- Agenda de reuniões:
https://calendly.com/tecnospeed
Qualquer dúvida, estamos à disposição.
Obrigado!