Fala Dev, beleza? Sou desenvolvedor na operação de PlugDfe da TecnoSpeed e vim lhe mostrar o passo a passo de como você, pode realizar as emissões de Nota fiscal eletrônica pelo PlugNotas.
Basicamente podemos dividir este artigo nos seguintes tópicos: -Cadastro de Software-house;
-Obter o TOKEN;
-Cadastro de certificado digital e empresa;
-Consumo das API’s (Cadastros, envio de nota, consulta, PDF e XML);
Cadastro de software-house:
Após a assinatura do contrato, é necessário se cadastrar no: https://conta.tecnospeed.com.br/ e criar sua conta.
https://conta.tecnospeed.com.br/register
Após realizar este cadastro, você já pode acessar a interface https://app2.plugnotas.com.br/, e realizar o login com os mesmos dados cadastrados no TecnoAccount.
Obter o token:
O Token (ou x-api-key) é o que utilizamos para te identificar em nossa base de dados, é com ele que nós identificamos se a requisição que estamos recebendo pertence a você ou a outra software-house e ele é único por software-house, independente do CNPJ.
Para obter o token, é necessário estar logado, ir até o nome da sua organização, e depois em Exibir Token:
Obs.: Este token é utilizado em todas as requisições da API, e deve ser informado nos headers da requisição como ‘x-api-key’
Cadastro de Certificado Digital:
Para podermos prosseguir, é necessário o cadastro do certificado digital do emissor em nossa plataforma, para podermos assinar as notas que iremos emitir, e para realizar este cadastro é muito simples e você também pode realizar este passo ou por interface, ou por API:
Interface:
Primeiro é necessário ir até a página de certificados clicando no menu lateral, após isso, podemos selecionar a opção “Novo” para escolher e inserir o novo certificado, informando o e-mail caso você queira ser avisado sobre o vencimento dele, e a senha do certificado
API:
Para realizar o cadastro via api, é necessário chamar o endpoint com o método post: https://api.plugnotas.com.br/certificado, informando a senha e o diretório do arquivo no body (multipart/form-data)
Exemplo de requisição:
curl --location 'https://api.plugnotas.com.br/certificado' \
--header 'x-api-key: {{token}}' \
--form 'senha="123456"' \
--form 'arquivo=@"/path/to/file"'
Será retornado um JSON com a seguinte estrutura:
{
"message": "Cadastro efetuado com sucesso",
"data": {
"id": "5ecc441a4ea3b318cec7f999"
}
}
Obs.: É importante salvar esse ID, ele será utilizado posteriormente no cadastro da empresa.
Cadastro de empresa:
O próxima passo é o de cadastrar a empresa emissora, ou seja, o emitente da NFe, que também pode ser realizado via interface, ou via API caso você queria deixar esta parte para o seu cliente.
Interface:
O módulo de cadastro de empresa é localizado na aba de empresas https://app2.plugnotas.com.br/#/empresas
Ao selecionar a opção “Novo”, irá aparecer as opções de cadastro que devem ser preenchidos de acordo com as informações do emitente (essa informação costuma a ser disponibilizada pelo emitente ou pelo contador dele), nesta configuração também é possível e necessário vincular o certificado já cadastrado na empresa.
API: Para realizar o cadastro via API, é necessário utilizar o seguinte endpoint com o método POST: https://api.plugnotas.com.br/empresa
Informando no body da requisição um JSON com as informações do emitente(exemplo de JSON de cadastro disponível aqui) :
Como resposta, você terá um JSON dessa forma:
{
"message": "Cadastro efetuado com sucesso",
"data": {
"cnpj": "23995875000176"
}
}
Obs.: É necessário vincular o certificado digital no cadastro da empresa, para fazer isso, é necessário informar o id do certificado obtido no passo anterior no atributo “certificado”.
Como posso realizar a emissão?
Agora finalmente podemos ir para a emissão, com todos os passos anteriores realizados, primeiramente é necessário preencher o JSON de envio com as informações da transação, e enviá-lo no body da requisição para o endpoint POST: https://api.plugnotas.com.br/nfe
E será retornado um JSON com a seguinte estrutura:
{
"documents": [
{
"idIntegracao": "XXXYY999",
"Emitente": "08187168000160",
"id": "5f1f7069af3fbe5296dfxxx"
}
],
"message": "Nota(as) em processamento",
"protocol": "0d09cf4b-6d94-42ed-8cf8-c687df91xxx"
}
O processamento é assíncrono, sendo assim, será necessário consultar esse ID na rota de consulta para verificar o status dela (também possuímos uma funcionalidade de notificação/webhook, que notifica sua aplicação quando o processamento é concluído)
Obs.: Também recomendo que seja salvo o “id”, dentro de documents[0].id, ele será utilizado posteriormente para as rotas de Consulta, Gerar PDF, e Gerar XML.
Como consultar uma nota?
Para consultar a nota, é necessário utilizar nossa rota de Consulta, informando o id no endpoint:
GET https://api.plugnotas.com.br/nfe/{idNotaorChave}/resumo
O retorno será um JSON com alguns dados da nota, incluindo seu Status:
[
{
"id": "5f9ad47eff3b4d0d7b4994ea",
"idIntegracao": "XXX999",
"emissao": "29/10/2020",
"status": "CONCLUIDO",
"destinada": false,
"emitente": "08187168000160",
"destinatario": "08114280956",
"valor": 9.2,
"numero": "1000013",
"serie": "805",
"chave": "41201008187168000160558050010000131609769080",
"protocolo": "141200000956123",
"dataAutorizacao": "29/10/2020",
"mensagem": "Autorizado o uso da NF-e",
"pdf": "https://api.plugnotas.com.br/nfe/5f9ad47eff3b4d0d7b4994ea/pdf",
"xml": "https://api.plugnotas.com.br/nfe/5f9ad47eff3b4d0d7b4994ea/xml",
"cStat": 100
}
]
Como consultar o XML da nota?
Para ter acesso ao XML é necessário consumir nossa rota de Obter XML, utilizando o mesmo id retornado no envio.
GET https://api.plugnotas.com.br/nfe/{idNotaorChave}/xml
Como retorno, você terá o exato XML que a SEFAZ nos retorna
Como obter o PDF da nota?
Para ter acesso ao PDF é necessário consumir nossa rota de Obter PDF, utilizando o mesmo id retornado no envio.
GET https://api.plugnotas.com.br/nfe/{idNota}/pdf
Como retorno, você obtém o PDF gerado pela nossa aplicação da nota em questão.
Estes são os passos básicos para você poder realizar suas emissões de NF-e utilizando nossa API PlugNotas, Caso deseje ter mais informações, vou estar deixando o link da nossa documentação oficial com exemplos e explicações de todas as rotas, Até mais dev!
Documentação: https://docs.plugnotas.com.br/