🔵 Como funciona na prática a emissão de NF-e com o PlugNotas?

[Matheus Henrique Bueno Barucho]

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/