ifsc-lased / composicao-paf-sef

Composição que permite facilmente montar um ambiente local de desenvolvimento composto pelas entidades PAF, SEFAZ autorizadora e SEF

Aviso de isenção de responsabilidade

A presente prova de conceito (POC) é um artefato fruto do Contrato de Encomenda Tecnológica nº 001/2020, firmado entre a Secretaria de Estado da Fazenda de Santa Catarina e o Instituto Federal de Santa Catarina - IFSC.

O objetivo desta prova de conceito é restrito aos objetivos contratados entre a SEF e o IFSC, compatível apenas com a versão 3.0.0 da especificação técnica de requisitos do DAF. Este artefato não tem como objetivo implementar completamente todos os processos de negócio previstos na especificação, visto que seu intuito foi demonstrar a viabilidade de implementação, tanto do DAF quanto da integração entre o PAF, DAF e a SEF-SC, utilizando tecnologias amplamente adotadas pelo mercado de desenvolvimento de software.

Não cabe à SEF ou ao IFSC prestar suporte sobre os componentes, códigos ou excertos de código disponíveis nesta POC, sendo a presente versão considerada final, sem previsão de alterações, correção de bugs ou melhorias.

A SEF e o IFSC eximem-se de qualquer responsabilidade, direta ou indireta, por perdas ou danos, comprovadamente ou alegadamente, causados pelos artefatos disponibilizados nesta POC. Caso deseje usar os componentes e softwares aqui disponibilizados, você estará fazendo isto exclusivamente por sua conta e risco.

Composição Docker com PAF, SEF e SEFAZ Autorizadora

Sumário

• Composição Docker com PAF, SEF e SEFAZ Autorizadora
  • Introdução
  • Composição Docker com PAF, SEF e SEFAZ Autorizadora
    • Casos de uso implementados pelo PAF
    • Requisitos para usar essa composição Docker
  • Como executar em um computador hospedeiro (Docker Host) executando o sistema operacional Linux
  • Como executar em um computador hospedeiro (Docker Host) executando o sistema operacional macOS
    • Executando o PAF localmente no computador hospedeiro
  • Personalizações opcionais da composição
    • Personalizações para desenvolvedores de PAF
    • Personalizações para fabricantes de DAF
  • Limitações conhecidas
    • Casos de uso não implementados
    • Valor do timeout da camada ARQ do protocolo de comunicação do DAF
    • Aplicação PAF
  • Dependências e bibliotecas de terceiros

Introdução

Na Especificação 3.0.0 do Dispositivo Autorizador Fiscal (DAF) são apresentados todos os casos de uso e protocolos que devem ser implementados pelo DAF para que o mesmo possa ser comandado pelo Programa Aplicativo Fiscal (PAF), bem como são listados todos os Serviços Web (Web Services) da Secretaria de Estado da Fazenda (SEF) que poderão ser consumidos pelo PAF para emissão de Nota Fiscal de Consumidor Eletrônica (NFC-e) em Santa Catarina no contexto do uso do Dispositivo Autorizador Fiscal (DAF), o que inclui o registro do DAF a validação de autorizações emitidas pelo mesmo.

Este repositório apresenta uma implementação de um Programa Aplicativo Fiscal (PAF), os Serviços Web da Secretaria do Estado da Fazenda de Santa Catarina (SEF) e uma implementação da SEFAZ Autorizadora e tem como público alvo desenvolvedores de PAF e fabricantes de DAF.

A implementação do PAF, da SEF e da SEFAZ autorizadora são disponibilizadas dentro de contêineres Docker e fazem parte do kit de desenvolvimento oferecido aos desenvolvedores de PAF e fabricantes de DAF. Na figura abaixo são apresentadas todas as entidades que fazem parte do kit de desenvolvimento.

1. DAF-pi
   • Implementação em Python3 de todos os casos de uso da Especificação 3.0.0 do Dispositivo Autorizador Fiscal (DAF) para ser executada exclusivamente em uma Raspberry Pi Zero W. O DAF-pi só pode ser usado como ferramenta de apoio para desenvolvimento do PAF, uma vez que a Raspberry Pi não atende os requisitos de segurança da especificação do DAF. O código fonte, bem como as instruções para instalar a imagem na Raspberry PI Zero W, estão disponíveis neste repositório.
     • O DAF-pi foi desenvolvido considerando que seria mais fácil para o desenvolvedor de PAF adquirir no mercado uma Raspberry Pi Zero W. Contudo, também foi feita uma prova de conceito de DAF, denominada DAF-poc, em um hardware com o microcontrolador MAX 32552 da Maxim. O código fonte desta prova de conceito pode ser obtido neste repositório.
2. Composição com PAF, SEF e SEFAZ Autorizadora (este repositório)
   • PAF
     • O PAF do kit de desenvolvimento só implementa as rotinas cruciais para interação com o DAF, SEFAZ autorizadora e SEF. Trata-se assim de uma ferramenta de apoio, para desenvolvedores de PAF e fabricantes de DAF, e não efetivamente um PAF que segue a especificação PAF-DAF publicada pela SEF.
   • SEFAZ Autorizadora
     • A SEFAZ Autorizadora no kit de desenvolvimento tem como foco somente o caso de uso para autorização de uso de DF-e. A implementação consiste de uma simples rotina de persistência do DF-e autorizado para uso no banco de dados relacional usado pelo PAF. Sendo assim, não consiste de uma implementação real da SEFAZ autorizadora.
   • Secretaria do Estado da Fazenda de Santa Catarina (SEF)
     • A SEF no kit de desenvolvimento provê implementação para todos os casos de uso que envolvam diretamente o contribuinte e seu DAF, conforme apresentado na Especificação 3.0.0 do Dispositivo Autorizador Fiscal (DAF), como por exemplo: registro de DAF, remoção de registro, autorização para remoção de autorização retida no DAF, entre outras.

Composição Docker com PAF, SEF e SEFAZ Autorizadora

Esta composição Docker ter objetivo ser uma ferramenta de apoio para desenvolvedores de PAF e fabricantes de DAF para que seus produtos possam ser desenvolvidos mesmo enquanto não existe uma implementação oficial dos serviços da SEF ou DAFs no mercado. O desenvolvedor de PAF poderá interagir com o DAF-pi e com os Serviços Web implementados, enquanto que o fabricante de DAF poderá controlar seu DAF por meio do PAF implementado nesta composição e interagir com a implementação da SEF.

O PAF desta composição consiste de uma aplicação web e uma vez que a composição for iniciada, poderá ser acessado por meio de navegador web apontando para o endereço http://localhost:5000. Os serviços da SEF poderão ser acessados por meio do endereço http://localhost:8080.

Este PAF consegue interagir com apenas um DAF por vez e conta com um contribuinte, juntamente com seu certificado digital, que simula um e-CNPJ A1, bem como outras informações que são necessárias para a comunicação do PAF com os serviços da SEF, como o idPAF.

O PAF desta composição considera apenas certificados digitais disponíveis no formato de arquivos no sistema de arquivo que o PAF tenha acesso. Ou seja, esta implementação não provê facilidades para usar certificados e-CNPJ A3. A implementação também não faz qualquer validação com relação à Autoridade Certificadora que emitiu o certificado. Todos os certificados usados neste projeto não estão de acordo com as regras da ICP-Brasil.

O PAF presente neste repositório é preparado para ser utilizado em conjunto com o DAF-pi. Uma vez que o PAF for iniciado, este irá buscar pelo dispositivo USB cujo string descriptor tenha o valor: DAF-SC. O PAF irá se associar com o primeiro dispositivo USB que ele encontrar. Sendo assim, caso possua mais de um DAF, garanta que somente um esteja conectado na porta USB do computador (hospedeiro) que está executando os contêineres Docker.

Casos de uso implementados pelo PAF

O Programa Aplicativo Fiscal (PAF) desta composição implementa os casos de uso essenciais para a interação com o DAF, tais como:

• Consultar informações do DAF
• Registrar o DAF
• Emitir Documentos Fiscais Eletrônicos (DF-e)
• Consultar autorizações retidas no DAF
• Apagar autorizações retidas no DAF
  • A SEF desta composição obtém as autorizações geradas pelo PAF para validá-las a cada 30 segundos.
• Alterar modo de operação do DAF
• Remover registro do DAF
• Cancelar processo do DAF

Além disso, este PAF provê facilidades exclusivas para o desenvolvedor, como:

• Consultar informações do DAF na SEF
• Remover o registro do DAF na SEF sem interagir com o DAF
• Colocar o DAF-pi no padrão de fábrica.

Requisitos para usar essa composição Docker

• Ter instalado o Docker e Docker Compose
• Sistema Operacional Linux ou macOS
  • A biblioteca Python usada no PAF para implementar o protocolo de comunicação com o DAF depende de funcionalidades presentes somente nos sistemas operacionais Linux ou macOS
  • Caso queira executar o PAF deste repositório em cima do sistema operacional Windows, então você precisará fazer a implementação do protocolo de comunicação para que funcione neste sistema operacional

Como executar em um computador hospedeiro (Docker Host) executando o sistema operacional Linux

Este é o cenário mais simples para subir o ambiente de desenvolvimento com um único comando. PAF, SEF e SEFAZ autorizadora são executados dentro de contêineres Docker.

Nesta composição foi feito uso do conceito de mapeamento de porta de comunicação serial (USB) do computador hospedeiro (Docker host) para dentro do contêiner onde estará sendo executado o PAF, permitindo assim que o PAF consiga interagir com o DAF que estará fisicamente conectado no computador hospedeiro.

No arquivo docker-compose.yml foi feito o mapeamento de dispositivos (/dev) do computador hospedeiro para dentro do contêiner onde o PAF é executado. Isso é necessário para que o PAF consiga interagir diretamente com o DAF, que estará fisicamente conectado na porta USB do computador hospedeiro.

Para obter o código fonte disponível neste repositório, basta executar o comando abaixo:

cd ~
git clone https://github.com/ifsc-lased/composicao-paf-sef

Em seguida, o usuário deve fazer o build da composição, executando os comandos abaixo:

cd composicao-paf-sef
docker-compose build

Uma vez que esse processo tenha sido finalizado, é preciso iniciar os serviços de banco de dados da composição. Esse processo pode demorar um pouco e é realizado por meio do seguinte comando:

docker-compose up -d db

É necessário aguardar que o processo anterior tenha sido finalizado, ou seja, o servidor MySQL dentro do contêiner deverá estar pronto para aceitar conexões. Por fim, pode-se executar os demais contêineres da composição com o comando abaixo:

docker-compose up

👏 Pronto! A composição está pronta para ser utilizada.

Como executar em um computador hospedeiro (Docker Host) executando o sistema operacional macOS

O Docker só permite fazer o mapeamento de dispositivos (/dev) do computador hospedeiro para o contêiner se o sistema operacional do computador hospedeiro for Linux. Sendo assim, se quiser usar o sistema operacional macOS, então o PAF deste repositório precisará ser executado localmente no computador hospedeiro e não dentro de um contêiner.

Obter o código fonte da composição

cd ~
git clone https://github.com/ifsc-lased/composicao-paf-sef

Fazer o build da composição e subir contêiner do MySQL

cd composicao-paf-sef
docker-compose build db sef
docker-compose up -d db

É necessário aguardar que o processo anterior tenha sido finalizado, ou seja, o servidor MySQL dentro do contêiner deverá estar pronto para aceitar conexões. Por fim, pode-se executar os demais contêineres da composição com o comando abaixo:

docker-compose up -d sef

Executando o PAF localmente no computador hospedeiro

Criar um ambiente virtual Python3.9 e instalar as dependências do PAF

cd paf/app
python3.9 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt
deactivate

Executar o PAF

sudo -s
source venv/bin/activate
python3.9 app.py

👏 Pronto! A composição e o PAF estão prontos para serem utilizados

Personalizações opcionais da composição

Esta composição está pronta para interagir com o DAF-pi. Entretanto, os desenvolvedores de PAF e fabricantes de DAF podem fazer algumas personalizações na mesma.

Personalizações para desenvolvedores de PAF

Caso o desenvolvedor de PAF queira substituir as informações do emitente, ou seja, alterar o CNPJ do contribuinte ou o certificado digital (e-CNPJ) que está configurado na composição, é necessário fazer modificações no arquivo db/init-script/contribuinte.properties. O exemplo abaixo apresenta a propriedades que devem ser modificadas.

cont_cnpj=00000000000000
cont_ecnpj_nome=arquivo-do-ecnpj-a1.pfx
cont_ecnpj_senha=senha-do-arquivo

Além disso, é necessário inserir o arquivo do certificado digital (no formato pfx) dentro da pasta paf/app/resources e fazer novamente o build da composição, por meio dos seguintes comandos:

cd ~/composicao-paf-sef
docker-compose stop
sudo rm -rf db/mysql_data
docker-compose build
docker-compose up -d db

É necessário aguardar que o processo anterior tenha sido finalizado, ou seja, o servidor MySQL dentro do contêiner deverá estar pronto para aceitar conexões. Por fim, pode-se executar os demais contêineres da composição com o comando abaixo:

docker-compose up 

Esse processo substitui as informações originais em toda a composição, ou seja, tanto no PAF quanto na SEF.

Personalizações para fabricantes de DAF

A SEF desta composição consegue interagir com um outro DAF que não seja o DAF-pi. Para isso, fabricante de DAF pode cadastrar o modelo do seu produto na SEF da composição modificando o arquivo db/init-script/contribuinte.properties. O exemplo abaixo apresenta as propriedades que podem ser modificadas.

certificado_sef=sef-ec-384.pkcs12
nomeModelo=modelo-daf
atestePub=chave-publica-de-ateste-daf 
versaSb=1
hash=resumo-do-software-basico
url=http://www.versaodaf1.com.br
fab_cnpj=00000000000000

A chave pública de ateste do DAF deve ser inserida no formato .pem e sem o cabeçalho e rodapé do arquivo que contém a chave, como no exemplo abaixo

Chave pública no formato .pem

-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAElNXZ/NYjXC0NbsDrsSEQptfGDiwKzr3K
K/Pndzt7dOVx70jITvLB5Zf9f2oA5+egrpMGIq/NFw8noDRPaz/CZn02kM0yAa4w
XRlpuPz1Ph4ihqWH+2qFFiOqdjp22S/0
-----END PUBLIC KEY-----

Chave pública modificada para ser inserida no arquivo db/init-script/contribuinte.properties

MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAElNXZ/NYjXC0NbsDrsSEQptfGDiwKzr3KK/Pndzt7dOVx70jITvLB5Zf9f2oA5+egrpMGIq/NFw8noDRPaz/CZn02kM0yAa4wXRlpuPz1Ph4ihqWH+2qFFiOqdjp22S/0

O fabricante de DAF deve armazenar o certificado da SEF no seu produto. Neste diretório tem um certificado com chave RSA e outro com chave EC. O fabricante deverá escolher um desses certificados de acordo com o algoritmo criptográfico que seu DAF é capaz de operar.

Feito isso, será necessário fazer novamente o build da composição, por meio dos seguintes comandos:

cd ~/composicao-paf-sef
docker-compose stop
rm -rf db/mysql_data
docker-compose build
docker-compose up -d db

É necessário aguardar que o processo anterior tenha sido finalizado, ou seja, o servidor MySQL dentro do contêiner deverá estar pronto para aceitar conexões. Por fim, pode-se executar os demais contêineres da composição com o comando abaixo:

docker-compose up 

A implementação SEF presente neste repositório opera com apenas um modelo novo de DAF por vez, ou seja, o modelo de DAF já cadastrado é sobrescrito cada vez que esse processo for realizado. Porém, o DAF-pi não é removido neste processo e continua disponível

Limitações conhecidas

Casos de uso não implementados

O Programa Aplicativo Fiscal (PAF) desta composição não implementa os seguintes processos:

• Obter impressão digital do certificado SEF armazenado no DAF
• Atualização do certificado digital da SEF no DAF
• Atualização do software básico do DAF
• Descarregar autorizações retidas no DAF
• Tratamento dos dados recebidos pelo DAF quando o mesmo está no modo inutilizado

Além disso, o PAF não implementa as interações junto à SEF com os seguintes serviços:

• Busca da chave PAF junto à SEF de um DAF já registrado
• Informar extravio do DAF junto à SEF
• Informar certificado SEF armazenado no DAF
• Solicitação de remoção da memória do DAF de documentos fiscais eletrônicos com rejeição
• Solicitação extraordinária para apagar autorizações retidas no DAF

A SEF desta composição também não implementa o serviço relativo ao endpoint DAFAutorizacaoRetida, especificado na seção 8.8 da Especificação Técnica de Requisitos 3.0.0 do DAF.

Valor do timeout da camada ARQ do protocolo de comunicação do DAF

Para que seja possível fazer a comunicação entre o PAF desta composição e o DAF-pi, o valor do timeout da camada ARQ do protocolo de comunicação com o DAF deste aplicativo é de 2 segundos, em desacordo com a Especificação 3.0.0 do Dispositivo Autorizador Fiscal (DAF). Esta mudança não impacta na comunicação entre o PAF e os demais DAFs.

Aplicação PAF

• Recomenda-se o uso do Google Chrome para acessar a aplicação PAF.
• Caso já tenha executado o PAF anteriormente, talvez seja necessário excluir os arquivos temporários de sessão (paf/app/flask_session) para o correto funcionamento da aplicação.

Dependências e bibliotecas de terceiros

Biblioteca	Função	Licença
Flask	Framework WEB	BSD-3-Clause
Flask-WTF	Formulários WEB	BSD
flask-sqlalchemy	Framework ORM	BSD-3-Clause
flask_bootstrap	Framework CSS	BSD
flask_fontawesome	Ícones	Apache e MIT
flask-nav	Menu principal	MIT
pymysql	Conexão com MySQL	MIT
pytest	Testes unitários	MIT
bradocs4py	Geradores de CPF, CNPJ e chave de acesso	MIT
PyNFe	Emissão e assinatura de NFC-e	LGPL-3.0
pytz	Dependência da biblioteca PyNFe, gerenciamento de fuso horário	MIT
weasyprint	Impressão em PDF	BSD
Flask-QRcode	Geração de QrCode	GPLv3
redis	Conexão com Redis	MIT
Flask-Session	Gerenciamento de Sessão	BSD
pyserial	Comunicação serial	BSD
PyJWT	Leitura dos tokens JWT	MIT
cryptography	Operações criptográficas	Apache 2.0 e BSD
Authlib	Dependência da biblioteca PyJWT	BSD