tecnospeed/plugnotas-php

Pacote para integração com o Plugnotas

Plugnotas

Este pacote foi construído com o objetivo de simplificar a integração com a API do Plugnotas. Para obter informações sobre o funcionamento e contratações acesse nosso site ou a documentação oficial.

Instalação

Adicionando o pacote

Aconselhamos a instalação do pacote pelo Composer. Composer é um gerenciador de dependências para PHP que lhe permite declarar e instalar as dependências em seu projeto de forma simplificada.

O pacote pode ser adicionado utilizando o comando do próprio composer:

php composer.phar require tecnospeedsa/plugnotas:~1.4

Ou adicionado manualmente no arquivo composer.json:

{
  "require": {
    "tecnospeedsa/plugnotas": "~1.4"
  }
}

O carregamento do pacote é realizado com o autoloader do Composer, caso você não tenha adicionado ao seu projeto é necessário incluir o seguinte require:

require 'vendor/autoload.php;'

Para maiores informações de como instalar, utilizar e melhores práticas para definir dependências em seu projeto acesse o site oficial getcomposer.org.

Utilizando o pacote

Envio de NFSe

Para enviar uma NFSe deve ser criado um objeto do tipo relacionado (TecnoSpeed\Plugnotas\Nfse), o qual é composto de vários outros objetos agrupados dentro de seu namespace.

Uma vez o objeto criado deve-se chamar o método send do mesmo, este processo pode ser bem complexo e extenso, não se preocupe existe uma forma mais fácil citada a seguir.

Um exemplo do envio de uma NFSe criando os objetos de forma manual pode ser encontrado aqui.

Criando uma NFSe com o auxiliar de builder

A classe TecnoSpeed\Plugnotas\Builders\NfseBuilder é uma classe auxiliar que permite você criar de forma fácil um objeto TecnoSpeed\Plugnotas\Nfse.

Com esta classe auxiliar utilizando os métodos: withTomador, withPrestador, withServico, withRps, withImpressao e withCidadePrestacao você pode compor o objeto Nfse, um exemplo disso é mostrado no arquivo nfse.simple.php.

Cadastro de Prestador, Tomador e Serviço

O cadastro de Prestador, Tomador e Serviço simplifica o envio da NFSe, sendo que uma vez cadastrado você pode enviar a nota com menos parâmetros pois o que já tem cadastrado será consultado.

Nos links a seguir você encontra exemplos dos cadastros dos tipos:

• Cadastro de Prestador
• Cadastro de Tomador
• Cadastro de Serviço

Consultando uma NFSe

Para consultar uma NFSe é necessário criar um objeto do tipo TecnoSpeed\Plugnotas\Configuration, setar ele num novo objeto TecnoSpeed\Plugnotas\Nfse utilizando o método setConfiguration.

Após este setup realizado, existe duas possibilidades de consulta, pelo ID da nota ou protocolo gerado na hora que você enviou a nota, ou passando o ID Integração e o CNPJ do Prestador utilizado para criar a NFSe. Os respectivos métodos são: findByCnpjAndIdIntegracao e findByIdOrProtocol.

Exemplo utilizando o método findByCnpjAndIdIntegracao pode ser encontrado aqui e exemplo utilizando o método findByIdOrProtocol pode ser encontrado aqui.

Download do PDF de uma NFSe

Da mesma forma que a consulta o download do PDF da Nfse necessita de um objeto do tipo TecnoSpeed\Plugnotas\Configuration, o qual deve ser setado num novo objeto TecnoSpeed\Plugnotas\Nfse utilizando o método setConfiguration. Uma particularidade é que é necessário indicar a pasta para escrita dos arquivos no objeto de configuração utilizando o método setNfseDownloadDirectory.

Existe a possibilidade de realizar o download utilizando o ID da nota retornado na criação utilizando o método download, como também realizar o download utilizando o CNPJ do Prestador e o ID Integração utilizados no envio da NFSe através do método downloadPdfByCnpjAndIdIntegracao.

Os arquivos serão salvos na pasta configurada (a qual precisa ter permissão de escrita), o padrão do nome do arquivo será o seguinte:

• Quando utilizado o método download: <pasta informada>/<id>.pdf
• Quando utilizado o método downloadPdfByCnpjAndIdIntegracao: <pasta informada>/<cnpj>-<id integração>.pdf

Exemplo de download utilizando o ID pode ser encontrado aqui e exemplo de download utilizando o CNPJ e ID Integração aqui.

Cancelamento

O cancelamento de uma NFSe pode ser realizado da mesma forma com que a busca e o download, informando o ID da Nfse ou o Cnpj do prestador e o ID Integração.

Da mesma forma que a consulta e o download do PDF da Nfse é necessário de um objeto do tipo TecnoSpeed\Plugnotas\Configuration, o qual deve ser setado num novo objeto TecnoSpeed\Plugnotas\Nfse utilizando o método setConfiguration.

Os respectivos métodos para realizar este procedimento são: cancel e cancelByCnpjAndIdIntegracao.

Ao criar um cancelamento será retornado um protocolo, tal protocolo pode ser utilizado para consultar o status do cancelamento utilizando a rota cancelStatus.

Exemplos

Você pode conferir alguns exemplos na pasta /examples.

Todos os objetos decompostos em arrays podem ser vistos no arquivo nfse.array.php.

Documentações oficiais

• Site do Plugnotas
• Documentação oficial
• Documentação da API

Changelog

Acesse o Changelog da aplicação por este link.

plugnotas-php's Issues

Consulta de CNPJ

Adicionar ao cliente PHP a consulta de CNPJ que já é disponível na API do Plugnotas.

A documentação da API pode ser encontrada em:
https://docs.plugnotas.com.br/#/Auxiliares/getCnpj

Observações:

• Para padronizar o código é interessante utilizar a Trait: Communication;
• É necessário criar testes que tenham sentido para o que está sendo codificado;

Erro instalando pacote

Ao instalar o pacote, utilizando o comando:
composer require tecnospeedsa/plugnotas
ocorre o seguinte erro:

1.
tecnospeedsa/plugnotas[1.4.3, ..., 1.5.2] require guzzlehttp/guzzle ~6.0 -> found guzzlehttp/guzzle[6.0.0, ..., 6.5.x-dev] but it conflicts with your root composer.json require (^7.0.1).

O pacote depende obrigatoriamente do guzzlehttp/guzzle versão 6, entretanto o mesmo já está na versão 7, então poderia ser feita alteração no composer.json para utilizar um ou outro: "^6.0|^7.0", mantendo-se compatibilidade.
Deveria ser validado o changelog entre as duas versão para saber se algum parâmetro utilizado foi depreciado ou alterado.

Sem essa alteração não é possível utilizar o pacote com a versão mais nova do guzzlehttp.

Atenciosamente.

Certificados

Adicionar ao cliente PHP a parte de Certificados que já é disponível na API do Plugnotas.

A documentação da API pode ser encontrada em:
https://docs.plugnotas.com.br/#tag/Certificado

Observações:

Para padronizar o código é interessante utilizar a Trait: Communication;
É necessário criar testes que tenham sentido para o que está sendo codificado;

Enviar mais de 1 Serviço na hora de emitir a NFSe

Adicionar ao pacote do plugnotas-php, a opção de enviar mais de um serviço ao emitir uma NFSe.

Adicionar ao cliente PHP a parte de enviar mais de um serviço que já é disponível na API do Plugnotas.

A documentação da API pode ser encontrada em:
https://docs.plugnotas.com.br/#operation/post-nfse

Observações:

É necessário criar testes que tenham sentido para o que está sendo codificado;

Adicionar endpoint de CRUD de empresa

Não tem nada no pacote referente a CRUD de empresas

Ausência das funções de atualizar e consultar

Boa Tarde!
Seria otimo se implementassem as funções de atualizar e consultar empresas (tomador e emissor) e serviços.

Adicionar comunicação com endpoint de Cidades Atendidas

Para um melhor controle de quais cidades é possível emitir pelo plugnotas, é necessário que o endpoint de cidades atendidas seja exposto no pacote.

Remover verificação/validação do campo CPF/CNPJ do tomador

Algumas prefeituras não validam o campo CPF ou CNPJ do tomador do serviço, como no RJ, e essa validação na API do PlugNotas inviabiliza a emissão NFSe para clientes que possuem um alto volume de notas a serem emitidos diariamente.

Atributo Quantidade de Serviços - Barueri/SP

A prefeitura de Barueri/SP exige que seja enviada a quantidade de serviços prestados.

servico.quantidade

$prestador = [...];
$tomador = [...];
$nfse = (new NfseBuilder)
                ->withPrestador($prestador])
                ->withTomador($tomador])
                ->withServico([
                    'quantidade' => 1,
                    ...
                ])
                ->build([])

A classe TecnoSpeed\Plugnotas\Nfse\Servico não possui o atributo quantidade, ignorando o valor enviado no array.

Adicionar CRUD de certificado digital

Não tem nada no pacote referente a CRUD de certificados digitais

Adicionar campos de configuração da NFSe ao criar/atualizar a empresa

Adicionar ao pacote do plugnotas-php, a opção de adicionar as configurações adicionais da NFSe ao criar/atualizar a empresa e que já é disponível na API do Plugnotas.

A documentação da API pode ser encontrada em:
https://docs.plugnotas.com.br/#operation/addCompany
https://docs.plugnotas.com.br/#operation/updateCompany

Cadastrar logotipo

Adicionar ao pacote do plugnotas-php, a opção de cadastrar um logotipo que já é disponível na API do Plugnotas.

A documentação da API pode ser encontrada em:
https://docs.plugnotas.com.br/#operation/post-empresa-cnpj-logotipo

Metodo setParcelas do Objeto Nfse precisa ser um Array e não somente um Objeto Parcelas

No Arquivo tecnospeedsa\plugnotas\src\Nfse.php na linha 230, o parametro precisa ser um array (igual na parte de serviços).

Isso impossibilita o envio de mais de uma parcela para nfse

CORRETO: public function setParcelas(array $parcelas)
COMO ESTA: public function setParcelas(Parcelas $parcelas)

Consulta de CEP

Adicionar ao cliente PHP a consulta de CEP que já é disponível na API do Plugnotas.

A documentação da API pode ser encontrada em:
https://docs.plugnotas.com.br/#/Auxiliares/getCep

Observações:

• Para padronizar o código é interessante utilizar a Trait: Communication;
• É necessário criar testes que tenham sentido para o que está sendo codificado;

Pacote desatualizado

Existem diversos campos na documentação na emissão de NFS-e que não estão mapeados aqui no pacote. Exemplos:

• Intermediário
• IBPT
• Na documentação fala que pode ser um array de serviços, aqui no pacote só vi a possibilidade de incluir 1.

Atualizar uma empresa

Adicionar ao pacote do plugnotas-php, a opção de atualizar a empresa.

Adicionar ao cliente PHP a parte de atualizar uma empresa que já é disponível na API do Plugnotas.

A documentação da API pode ser encontrada em:
https://docs.plugnotas.com.br/#operation/updateCompany

Versão do Componente

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - tecnospeedsa/plugnotas[1.4.0, ..., 1.5.4] require php ^7.0 -> your php version (8.0.3) does not satisfy that requirement.
    - Root composer.json requires tecnospeedsa/plugnotas ~1.4 -> satisfiable by tecnospeedsa/plugnotas[1.4.0, ..., 1.5.4].

Seria possível liberar a versão para o PHP 8 também?
E não entendi muito bem que erro está se referendo a versão, alguma ideia do que possa estar causando isso?

Composer version 2.0.11 2021-02-24 14:57:23