Kleverson Cruz Postado Julho 18, 2023 Compartilhar Postado Julho 18, 2023 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 1 Link to comment Compartilhe em outros sites Outras opções de compartilhamento...
Postagens Recomendadas
Crie uma conta ou entre para comentar 😀
Você precisa ser um membro para deixar um comentário.
Crie a sua conta
Participe da nossa comunidade, crie sua conta.
Criar minha conta agoraÉ bem rápido!
Entrar
Você já tem uma conta?
Entrar agoraFaça o login agora.