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

[Marcos Santos]

Olá Dev, como vai? Eu sou o Marcos desenvolvedor da operação PlugDfe da TecnoSpeed e vou te apresentar o passo a passo para realizar sua primeira emissão de uma Nota do Consumidor no Plugnotas.

 

Para a sua primeira emissão de NFC-e é necessário realizar alguns passos para conseguir ser bem sucedida. É necessário  seguir os passos a seguir, que estão também em uma outra documentação nossa sobre como realizar a emissão de uma NF-e no Plugnotas.

Cadastro de Software-house

O token da API.

Um cadastro de certificado digital vinculado a sua empresa, a API Plugnotas também possui uma rota de cadastro de certificados e com esse certificado você como DEV consegue emitir não apenas uma NFC-e e sim todos os outros documentos que a carteira do Plugnotas oferece.

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

 

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)

curl --location 'https://api.plugnotas.com.br/certificado' \

--header 'x-api-key: {{token}}' \

--form 'senha="123456"' \

--form 'arquivo=@"/path/to/file"'

 

Resposta:

{
  "message": "Cadastro efetuado com sucesso",
  "data": {

    "id": "5ecc441a4ea3b318cec7f999"
  }
}

 

Cadastro de empresa:
O próximo passo é o de cadastrar a empresa emissora, ou seja, o emitente da NFC-e, que também pode ser realizado via interface, ou via API caso você queira 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ão 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

 

Resposta:

{

    "message": "Cadastro efetuado com sucesso",

    "data": {

    "cpfCnpj": "93879866000103"

	}
}

 

Realizando sua primeira emissão de NFC-e:
Aṕos realizado os passos anteriores você como DEV está apto a realizar sua primeira impressão NFC-e no Plugnotas. Será necessário enviar o JSON com todos os campos preenchidos e corretos para a rota da API (exemplo de JSON de cadastro aqui

 

Resposta:

{

  "documents": [

    {

      "idIntegracao": "XXXYY999999",

      "Emitente": "08187168000160",

      "id": "5f6cb8936d8b321859b8fxxx"

    }

  ],

  "message": "Nota(as) em processamento",

  "protocol": "d6aafd45-c85f-40eb-ab02-c46d1855002f"

}

 

Um detalhe importante e interessante sobre a API dos Plugnotas é a padronização no envio dos documentos fiscais, todas as emissões possuem um mesmo padrão que facilita e torna muito mais fácil a integração com outros documentos.

O processamento da emissão é feita de forma assíncrona  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)

 

Como realizar a consulta da nota?

A consulta da nota é feita através da rota de Consulta, onde é necessário passar o id gerado no momento da emissão.
 

curl --request GET \

  --url https://api.plugnotas.com.br/nfce/{idNota}/resumo

Resposta:

[

  {

    "id": "5f6cb8936d8b321859b8fxxx",

    "idIntegracao": "XXXYY999999",

    "emissao": "24/09/2020",

    "status": "CONCLUIDO",

    "emitente": "08187168000160",

    "destinatario": "08114280956",

    "valor": 4.6,

    "numero": "985201",

    "serie": "774",

    "chave": "41200908187168000160657740009852011712708654",

    "protocolo": "141200000499373",

    "dataAutorizacao": "24/09/2020",

    "mensagem": "Autorizado o uso da NFC-e",

    "pdf": "https://api.plugnotas.com.br/nfce/5f6cb8936d8b321859b8fxxx/pdf",

    "xml": "https://api.plugnotas.com.br/nfce/5f6cb8936d8b321859b8fxxx/xml"

  }

]

 

Como obter o xml da nota?

Para ter acesso ao XML é necessário consumir nossa rota de Obter XML, utilizando o mesmo id retornado no envio ou chave da nota.
 

curl --request GET \

  --url https://api.plugnotas.com.br/nfce/{idNota}/xml \

  --header 'x-api-key: '

 

Resposta:
 

RETORNA O XML DESTINATÁRIO

 

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 ou chave da nota.
 

curl --request GET \

  --url https://api.plugnotas.com.br/nfce/{idNota}/pdf \

  --header 'x-api-key: '

Resposta:

RETORNA O PDF EM BYTES

Realizando esses passos você vai conseguir realizar as emissões de NFC-e utilizando a API do Plugnotas, a nossa API oferece também muitas outras funcionalidades que vão facilitar sua vida como dev. Até e obrigado pela leitura deste artigo, espero que tenha te ajudado.

Documentação: https://docs.plugnotas.com.br/