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

[Kleverson Cruz]

Oi, pessoal! Tudo bem?

Hoje gostaria de compartilhar com vocês um guia sobre como utilizar a API PlugNotas para emitir Notas Fiscais de Serviço Eletrônicas (NFS-e) de forma prática. Com um único JSON é possível emitir notas de forma simplificada, independentemente do padrão de webservice ou da cidade de prestação.

 

Acesso à API:
Antes de iniciar o processo, verifique se você possui a chave de API necessária para autenticar suas requisições. Para este guia, vamos utilizar o ambiente Sandbox da API PlugNotas, que oferece respostas fixas e permite testes sem a necessidade de informar um prestador devidamente credenciado.

Endpoint utilizado será: https://api.sandbox.plugnotas.com.br/
Informe o token 2da392a6-79d2-4304-a8b7-959572c7e44d no cabeçalho x-api-key como autenticação para todas as suas requisições.

Cabeçalho x-api-key preenchido com token de sandbox

Caso esteja utilizando o ambiente de produção, o endpoint será: https://api.plugnotas.com.br/
Para obter o token de produção, siga os passos descritos na documentação: Obtendo o Token

Certifique-se de ajustar o endpoint e o token de acordo com o ambiente que você está utilizando. 
Agora, vamos prosseguir com os passos para emitir uma NFS-e.

 

Cadastrar certificado:
O primeiro passo é cadastrar um certificado digital. Para isso, utilize a rota POST /certificado e inclua na requisição um form-data contendo o arquivo do certificado e a respectiva senha. 
A obrigatoriedade do certificado pode variar de acordo com cada prefeitura ou webservice. Caso queira verificar se uma cidade utiliza certificado, você pode utilizar a rota GET /nfse/cidades.

O arquivo do certificado deve ser informado em corpo no formato form-data.

 

Cadastrar prestador:
Agora vamos realizar o cadastro do prestador enviando uma requisição POST para a rota /empresa. No corpo da requisição, além dos dados básicos da empresa, inclua o campo "nfse" com as configurações de número de RPS (Recibo Provisório de Serviços), ambiente de emissão e autenticação da prefeitura.
Certifique-se também de incluir o campo "certificado" com o ID obtido no passo anterior, para vincular o certificado ao cadastro do prestador.

{
    "cpfCnpj": "71073473000167",
    "inscricaoMunicipal": "8214100099",
    "simplesNacional": true,
    "regimeTributario": 1,
    "razaoSocial": "Tecnospeed S/A",
    "certificado": "64b58c5405f34cdce812efc1",
    "endereco": {
        "bairro": "Zona 01",
        "cep": "87020025",
        "codigoCidade": "4115200",
        "estado": "PR",
        "logradouro": "Duque de Caxias",
        "numero": "882",
        "tipoLogradouro": "Avenida",
        "codigoPais": "1058",
        "complemento": "17 andar",
        "descricaoCidade": "Maringá",
        "descricaoPais": "Brasil",
        "tipoBairro": "Zona"
    },
    "nfse": {
        "ativo": true,
        "tipoContrato": 0,
        "config": {
            "producao": true,
            "rps": {
                "lote": 1,
                "numeracao": [
                    {
                        "numero": 1,
                        "serie": "RPS"
                    }
                ]
            },
            "prefeitura": {
                "login": "teste",
                "senha": "teste123"
            }
        }
    }
}

 

Emitir NFS-e
Após o cadastro do prestador, você estará pronto para emitir uma NFS-e. Para isso, envie uma requisição POST para a rota /nfse, incluindo um JSON com as informações da nota de serviço. Vamos destacar algumas das propriedades obrigatórias que compõem esse JSON

• Prestador: Deve ser informado o CPF/CNPJ e outros dados relevantes do prestador de serviço, conforme necessário. Por padrão serão utilizados os dados do cadastro realizado previamente.
• Tomador: Nesse campo, devem ser fornecidos os dados do tomador do serviço, como CPF/CNPJ, razão social, endereço e e-mail.
• Serviço: Aqui, serão informados os detalhes do serviço prestado, como código, discriminação, valor a ser cobrado e impostos aplicáveis.

Com os campos devidamente apresentados podemos montar o JSON:

[
  {
    "prestador": {
      "cpfCnpj": "82186217000100"
    },
    "tomador": {
      "cpfCnpj": "99999999999999",
      "razaoSocial": "Empresa de Teste LTDA",
      "email": "teste@plugnotas.com.br",
      "endereco": {
        "descricaoCidade": "Maringa",
        "cep": "87020100",
        "tipoLogradouro": "Rua",
        "logradouro": "Barao do rio branco",
        "tipoBairro": "Centro",
        "codigoCidade": "4115200",
        "complemento": "sala 01",
        "estado": "PR",
        "numero": "1001",
        "bairro": "Centro"
      }
    },
    "servico": [
      {
        "codigo": "14.10",
        "codigoTributacao": "14.10",
        "discriminacao": "Descrição dos serviços prestados",
        "cnae": "7490104",
        "iss": {
          "tipoTributacao": 7,
          "exigibilidade": 1,
          "aliquota": 3
        },
        "valor": {
          "servico": 1
        }
      }
    ]
  }
]

A emissão da NFS-e é um processo assíncrono. Você receberá um protocolo e um ID que serão utilizados para consultar a situação da nota posteriormente.
Se não houver erros de validação em sua requisição, você receberá a seguinte resposta:

{
    "documents": [
        {
            "id": "64b5445a47188375a92f6414"
        }
    ],
    "message": "Nota(as) em processamento",
    "protocol": "22535d12-b458-4b12-b5d2-37c46f1f01ae"
}

 

Consultar NFS-e

Após a emissão é necessário enviar uma requisição GET para /nfse/consultar/{idouprotocolo} a fim de verificar a situação da nota emitida. Essa consulta permitirá obter informações sobre o status atual da NFS-e.
Durante o processo de consulta, você pode encontrar os seguintes status:

• PROCESSANDO: Indica que a nota está em processamento. Nesse caso, é necessário realizar consultas subsequentes até obter a situação final da nota.
• REJEITADO: Caso ocorra algum erro durante a emissão da nota, você receberá esse status juntamente com o motivo da rejeição. Analise a mensagem de erro, ajuste os dados do JSON de envio e tente a emissão novamente.
• CONCLUÍDO: Indica que a NFS-e foi devidamente autorizada. No ambiente Sandbox, todas as emissões resultarão em sucesso.

Ao consultar uma nota concluída, você receberá os seguintes dados:

[
    {
        "id": "64b5445a47188375a92f6414",
        "emissao": "17/07/2023",
        "situacao": "CONCLUIDO",
        "prestador": "82186217000100",
        "tomador": "99999999999999",
        "valorServico": 1,
        "numeroNfse": "22143",
        "serie": "LAL",
        "lote": 290008,
        "numero": 7,
        "codigoVerificacao": "5278FE6A7",
        "autorizacao": "17/07/2023",
        "mensagem": "RPS Autorizada com sucesso",
        "pdf": "https://api.sandbox.plugnotas.com.br/nfse/pdf/64b5445a47188375a92f6414",
        "xml": "https://api.sandbox.plugnotas.com.br/nfse/xml/64b5445a47188375a92f6414"
    }
]

 

Exportar NFS-e

Após consultar a NFS-e e obter a situação "CONCLUÍDO", você pode exportar a nota nos formatos PDF ou XML. Para isso, basta realizar as seguintes operações:
Para exportar o PDF da nota, faça uma requisição GET para /nfse/pdf/{idNota}. Isso permitirá que você obtenha o arquivo PDF contendo os dados da NFS-e.
Para exportar o XML da nota, faça uma requisição GET para /nfse/xml/{idNota}. Isso permitirá que você obtenha o arquivo XML gerado pela prefeitura.

PDF obtido ao exportar.

E assim concluímos o guia de utilização da API PlugNotas para emissão de NFS-e. Espero que este guia tenha sido útil e fornecido todas as informações necessárias para você começar a utilizar a API em seus projetos.

Caso queira explorar mais detalhes, exemplos e informações adicionais, recomendo que consulte a documentação completa, disponível no seguinte link: Documentação API PlugNotas