Configurações do Extrato

Vários detalhes da impressão dos extratos podem ser configurados.

Se você realizar a impressão de um extrato de CF-e-SAT, de venda ou de cancelamento, sem especificar qualquer configuração, a biblioteca irá utilizar valores padrão, que estão descritos mais adiante.

Porém, você poderá manter um arquivo em disco em um formato ini, fácil para que tanto um usuário com um editor textos possa modificar manualmente, quanto para um sistema fornecer uma interface fácil de usar para alterar as configurações dos extratos.

Para carregar um arquivo de configurações faça:

from satextrato import config
conf = config.carregar()

Se você não especificar um arquivo de onde carregar, a biblioteca irá tentar obter tanto o caminho, como o nome do arquivo a partir das varíaveis de ambiente SATEXTRATO_CONFIG_DIR e SATEXTRATO_CONFIG_FILENAME, respectivamente.

Se a variável SATEXTRATO_CONFIG_DIR não existir, será utilizado um caminho padrão a partir do diretório raiz do usuário (home em ambiente unix/linux) chamado ~/.satextrato. Se este caminho não existir, será criado. Se a variável SATEXTRATO_CONFIG_FILENAME não existir, será utilizado um nome de arquivo padrão chamado satextrato.ini.

Para carregar as configurações a partir de um caminho específico, faça:

from satextrato import config
conf = config.carregar(arquivo='/caminho/para/arquivo.ini')

Se o arquivo /caminho/para/arquivo.ini não existir, durante o carregamento o arquivo especificado será criado com as configurações padrão. Abaixo, o conteúdo de um arquivo de configurações com os valores padrão:

[cupom]
itens_modo_condensado = yes
exibir_nome_consumidor = no
avancar_linhas = 7
cortar_documento = yes
cortar_parcialmente = yes
cortar_avanco = 0

[rodape]
esquerda = Extrato CF-e-SAT
direita = http://git.io/vJRRk

[code128]
ignorar = no
altura = 56
quebrar = yes
quebrar_partes = 22, 22
truncar = no
truncar_tamanho = 44

[qrcode]
tamanho_modulo = 4
nivel_correcao = L
nome_aplicativo = De Olho Na Nota
mensagem_modo_condensado = yes
mensagem = Consulte o QRCode pelo aplicativo De Olho Na Nota, disponivel na AppStore (Apple) e PlayStore (Android)

Seção cupom

Corpo do extrato e opções para finalização do cupom.

Opção	Tipo	Comentários
itens_modo_condensado	bool	Indica se os itens deverão ser impressos em modo condensado. Senão, serão impressos no modo normal.
exibir_nome_consumidor	bool	Indica se o nome do consumidor (se houver) deverá ser impresso no extrato. Normalmente, apenas o número do documento é impresso.
avancar_linhas	int	Número de linhas a avançar no final do documento, antes de guilhotinar (se for o caso).
cortar_documento	bool	Indica se ao final do documento a guilhotina deverá ser acionada (se disponível).
cortar_parcialmente	bool	Indica se o documento deverá ser apenas parcialmente guilhotinado. Esta opção terá efeito apenas se cortar_documento estiver ligada.
cortar_avanco	int	Valor multiplicador do avanço em unidades de impressão. Use para evitar que a guilhotina corte em local errado, efetuando o corte sobre parte do conteúdo.

O avaço de linhas será honrado mesmo que a opção para cortar o documento esteja ligada e a impressora possuir uma guilhotina. Isso é útil devido ao fato de que a posição do cabeçote de impressão (e isso depende de cada modelo de impressora) pode requerer que o documento avançe um pouco antes da guilhotina ser acionada, para evitar que o documento seja cortado com dados abaixo da guilhotina. Além disso, nem todos os modelos de impressoras são capazes de honrar o valor configurado em cortar_avanco.

Seção rodape

Opções para configuração do rodapé.

Opção	Tipo	Comentários
esquerda	str	Texto (curto) para ser exibido no rodapé do extrato, à esquerda da borda do cupom.
direita	str	Texto (curto) para ser exibido no rodapé do extrato, à direita da borda do cupom.

Seção code128

Opções para impressão do código de barras Code128. Este código contém os quarenta e quatro dígitos da "Chave de Acesso" que identifica o documento fiscal.

Opção	Tipo	Comentários
ignorar	bool	Ignora a impressão do código de barras.
altura	int	Determina a altura das barras. Para saber o significado desse valor, consulte a documentação da PyESCPOS.
quebrar	bool	Indica se o código de barras deverá ser quebrado em partes. Mais detalhes abaixo.
quebrar_partes	str	Lista de tamanhos para quebra do código de barras. Mais detalhes abaixo.
pular_linha_entre_partes	bool	Indica se deve ser pulada uma linha (line feed) entre cada parte do Code128.
truncar	bool	Indica se o código de barras deverá ser truncado ao invés de ser quebrado. Um código truncado irá renderizar apenas um número especificado de dígitos da chave de acesso.
truncar_tamanho	int	Se for para truncar, esta propriedade indica quantos digitos da chave de acesso serão considerados na impressão do código.

As opções para truncar e quebrar o código de barras são mutuamente exclusivas e truncar possui precedência sobre quebrar. Veja os detalhes sobre estas opções, a seguir.

A motivação para quebrar o código de barras é devido a uma limitação em que certos modelos de impressoras podem não ser capazes de imprimir todos os 44 dígitos da chave de acesso em uma única linha. Assim, o código de 44 dígitos pode ser quebrado em partes para tornar a impressão possível. Por exemplo, para quebrar o código em duas partes, você poderá especificar quebrar_partes = 22,22, ou seja, duas partes com 22 dígitos cada. Certas impressoras com bobinas muito estreitas podem ter uma quebra especificada em mais partes com menos dígitos em cada parte. A regra é que a lista em quebrar_partes deverá especificar apenas números inteiros, pares, maiores que zero, cuja soma seja igual a 44.

Truncar é uma opção que lhe permitirá imprimir o código de barras contendo apenas parte dos dígitos da chave de acesso. Truncar tem precedência sobre a quebra, o que significa que, se a opção truncar estiver ligada, então a opção para quebra será ignorada.

Algumas impressoras, ao renderizar um código de barras Code128, realizam um avanço (line feed) automático. Outras impressoras não tem esse comportamento, o que acaba deixando as partes do Code128 sem nenhum espaço entre elas. Ligar ou desligar a opção pular_linha_entre_partes lhe permite algum controle sobre essa característica.

Seção qrcode

Código bidimensional QRCode e a mensagem logo após, sobre o aplicativo para autenticação/validação do documento emitido. O código QR contém diversas informações à respeito do documento fiscal. Para detalhes, consulte a "Especificação de Requisitos" do SAT-CF-e e/ou o "Manual de Orientação".

Opção	Tipo	Comentários
tamanho_modulo	int	Tamanho do módulo QRCode. Consulte a documentação da PyESCPOS para mais detalhes sobre esta opção.
nivel_correcao	str	Nível de correção de erros. Consulte a documentação da PyESCPOS para mais detalhes sobre esta opção.
nome_aplicativo	str	Nome do aplicativo capaz de consultar a validade do documento fiscal através do QRCode impresso no extrato. Veja sobre isso mais adiante.
mensagem_modo_condensado	bool	Se a mensagem deverá ser impressa em modo condensado ou em modo normal de impressão.
mensagem	str	Mensagem a ser impressa logo após o QRCode. Veja sobre isso mais adiante.

A mensagem a ser impressa logo após o QRCode normalmente irá instruir o consumidor a utilizar um certo aplicativo que, em tese, é capaz de verificar a autenticidade do documento fiscal que aquele extrato representa.

Salvando as Configurações

Para salvar as configurações faça:

from satextrato import config
conf = config.carregar()  # retorna um objeto collections.namedtuple

# objetos namedtuple são imutáveis, para modificar os atributos é preciso
# usar o método _replace() que retorna um novo objeto namedtuple:
conf = conf._replace(
        rodape=conf.rodape._replace(
                esquerda='Novo Texto Esquerda',
                direita='Novo Texto Direita'
            )
    )

# salva as configurações modificadas
config.salvar(conf, arquivo='/caminho/para/arquivo.ini')

Objeto satextrato.config.Configuracoes

Quando você invoca as funções satextrato.config.carregar() ou satextrato.config.padrao(), estas funções retornam uma instância de collections.namedtuple com as seguintes propriedades:

from satextrato import config
conf = config.padrao()  # retorna um objeto satextrato.config.Configuracoes

conf.cupom  # satextrato.config.Cupom
conf.cupom.itens_modo_condensado  # bool
conf.cupom.exibir_nome_consumidor  # bool
conf.cupom.avancar_linhas  # int
conf.cupom.cortar_documento  # bool
conf.cupom.cortar_parcialmente  # bool
conf.cupom.cortar_avanco  # int

conf.rodape  # satextrato.config.Rodape
conf.rodape.esquerda  # str
conf.rodape.direita  # str

conf.code128  # satextrato.config.Code128
conf.code128.ignorar  # bool
conf.code128.altura  # int
conf.code128.quebrar  # bool
conf.code128.quebrar_partes  # tuple(int, ...)
conf.code128.truncar  # bool
conf.code128.truncar_tamanho  # int

conf.qrcode  # satextrato.config.QRCode
conf.qrcode.tamanho_modulo  # int
conf.qrcode.nivel_correcao  # str
conf.qrcode.nome_aplicativo  # str
conf.qrcode.mensagem_modo_condensado  # bool
conf.qrcode.mensagem  # str

Variáveis de Ambiente

A partir da versão 0.4, a biblioteca satextrato passa a depender da biblioteca python-decouple, que torna muito mais fácil lidar com variáveis de ambiente, principalmente se sua aplicação estiver carregando-as a partir de arquivos .env ou .ini.

As seguintes variáveis de ambiente são consideradas:

Varíável de Ambiente	Valor Padrão	Comentários
SATEXTRATO_CONFIG_DIR	~/.satextrato	Caminho onde deve ser encontrado ou gravado o arquivo de configurações.
SATEXTRATO_CONFIG_FILENAME	satextrato.ini	Nome do arquivo de configurações.
SATEXTRATO_UNIDECODE_VALUES_ON_PY2	t	Determina se os valores das configurações deverão ser transliterados (via Unidecode quando estiver executando sob Python 2. O valor desta variável deverá ser y, yes, t, true, on ou 1 para ser considerado verdadeiro (True) e só terá efeito quando estiver executando sob Python 2.
SATEXTRATO_SECAO_CUPOM	cupom	Nome da seção que contém as configurações do cupom.
SATEXTRATO_SECAO_RODAPE	rodape	Nome da seção que contém as configurações do rodapé.
SATEXTRATO_SECAO_CODE128	code128	Nome da seção que contém as configurações do Code128.
SATEXTRATO_SECAO_QRCODE	qrcode	Nome da seção que contém as configurações do QRCode.