Guia Geral - Componente CF-e SAT

O Componente CF-e da Tecnospeed é uma biblioteca contendo todos os métodos necessários para emitir Cupom Fiscal Eletrônico SAT. É a escolha ideal para quem pode consumir OCX e prefere manter todo o processo de mensageria do CF-e dentro do próprio ambiente. Para utilizar o Componente em seu software, basta instanciá-lo em seu projeto, implementar chamadas para cada um dos métodos e configurá-los de acordo com sua necessidade.

Com isso reunido, você poderá seguir este passo a passo detalhado:

1. Instalando o Componente CF-e SAT
2. Configurar SAT
3. Instanciar Componente CF-e SAT
4. Configurando as propriedades
5. Entendendo o fluxo de emissão
6. Gerando o arquivo de integração
7. Validando um XML
8. Retornos
9. Enviar Cupom
10. Imprimir Cupom
11. Cancelar Cupom

Instalar Componente CFe SAT

Após aprovação do pedido de adesão, em até 24 horas úteis, nossa equipe financeira irá realizar o faturamento e disponibilizar o Componente CF-e SAT para download na Central do Cliente. Você pode acessar a Central do Cliente com os dados de acesso que você preencheu no formulário de registro.

Com o Componente já disponível, na aba lateral Download, clique no botão Baixar. Caso o download não inicie, desabilite o bloqueador de pop-ups do seu navegador.

Existem dois instaladores disponíveis para download na Central do Cliente: O Setup SAT Full e o Setup SAT Dependencies. O primeiro deve ser instalado no ambiente de desenvolvimento e o segundo no ambiente onde o sistema for ser executado.

No ambiente de desenvolvimento

No ambiente de desenvolvimento, nós devemos instalar a versão Full, pois ela é a biblioteca completa, com todos os métodos e arquivos que o componente possui. Para instalá-la, basta executar o instalador e seguir as instruções na tela.

No ambiente do cliente

No ambiente onde o sistema for ser executado, devemos instalar a versão Dependencies, que é a versão Full reduzida, com apenas as DLLs necessárias para o componente funcionar. Para instalá-la, existem algumas opções: é possível simplesmente executar o instalador, como na versão Full, executar o instalador em modo silencioso, ou incluir as DLLs no seu próprio instalador.

Além das DLLs, é necessário que o componente tenha acesso às pastas de Esquemas e Templates e aos arquivos com o endereço dos servidores. Estas pastas e arquivos são criados no diretório de instalação da versão Full (TecnoSpeed/CFeSAT/Arquivos). É necessário colocá-los no ambiente do cliente e configurar o diretório delas nas propriedades DiretorioEsquemas, DiretorioTemplates, ArquivoServidoresHom e ArquivoServidoresProd.

Modo Silencioso

Para evitar que o usuário precise realizar alguma interação, é possível incorporar um comando na sua aplicação ou instalador. Existem dois comandos disponíveis: Silent e VerySilent. O comando Silent irá exibir a interface de instalação, mas não permitirá que o usuário interaja com o instalador. Por outro lado, o comando VerySilent não exibirá nenhuma interface ao usuário, a instalação será executada em segundo plano.

prompt> instalador.exe /silent
prompt> Instalador.exe /verysilent

Incluindo os arquivos no próprio instalador

O instalador das dependências apenas adiciona as DLLs onde ele é instalado. Para não utilizar o instalador, é possível incorporar as DLLs ao próprio instalador. Basta copiar ou registrar na pasta System32, caso o sistema seja 64 bits, e na pasta SysWOW64 para a versão de 32 bits do Windows.

DLLs que devem ser registradas:

• CFeSatX.ocx
• CFeSatDataSetX.dll
• msxml6.dll
• CFeSatGovX.ocx
• midas.dll
• stdvcl40.dll

DLLs que devem ser apenas copiadas:

• ssleay32.dll
• libeay32.dll
• msxml6r.dll

Instalação Manual

A instalação manual trata-se do usuário instalar o componente CF-e SAT através de seu arquivo binário na extensão .dpk (Delphi Package). Caso opte em instalar o componente manualmente siga as instruções abaixo:

• Atenção! É necessário que seja instalado a versão Dependencies no ambiente de Desenvolvimento e do cliente;

• Deverá ter em mãos o dpk do componente CF-e SAT na versão de Delphi desejada e abri-lo.

• Incluir no search path do projeto o caminho das BPL´s e DCP´s da GOV, exemplo:

• Após inserir os search path, deve-se compilar o projeto e o mesmo não poderá ter nenhum erro.

• Ao compilar o projeto anteriormente, será criado um arquivo BPL e DCP do componente no diretório específico do Delphi, segue exemplos de diretórios:
  • C:\Users\Public\Documents\Embarcadero\Studio\17.0\Bpl;
  • C:\Users\Public\Documents\Embarcadero\Studio\17.0\Dcp;
    • Obs. Esse diretório é somente um exemplo, cada versão do Delphi tem seu respectivo diretório. Exemplo:
    • Delphi Seattle - C:\Users\Public\Documents\Embarcadero\Studio\17.0;
    • Delphi XE6 - C:\Users\Public\Documents\Embarcadero\Studio\14.0;
    • Delphi XE3 - C:\Users\Public\Documents\RAD Studio\10.0;
    • Delphi XE - C:\Users\Public\Documents\RAD Studio\8.0;

• Será necessário copiar as BPL´s e DCP´s da GOV que são as mesmas colocadas no search path do projeto anteriormente, para o diretório específico do Delphi conforme citado alguns exemplos acima, onde são criados os arquivos BPL e DCP do componente, exemplo:

• Após realizar esses passos, poderá finalmente instalar o seu componente CF-e SAT, conforme a imagem abaixo:

Configurar SAT

Nesse ponto, você deve instalar e configurar o aparelho o SAT para poder gerar as emissões. O ambiente de envio (produção ou homologação) é definido no momento da compra do aparelho.

As fabricantes disponibilizam os aparelhos de produção, que é o que os estabelecimentos devem comprar para realizar as emissões no dia a dia, mas também disponibilizam os aparelhos de desenvolvimento, que estão configurados para emitir cupons em homologação. O aparelho SAT de desenvolvimento deve ser usado apenas em ambientes de testes e durante o desenvolvimento, ele não faz os envios de XMLs autorizados para a SEFAZ.

No caso de ambientes de desenvolvimento, o Emulador da SEFAZ pode ser utilizado e é justamente sobre ele que vamos falar. O Emulador, é um aplicativo que simula o aparelho SAT, sem a necessidade de usar um aparelho físico. Ele é um aplicativo JAVA disponibilizado pela SEFAZ em seu próprio portal.

Com o Emulador, é possível emitir e autorizar cupons de forma prática, mas ele deve ser usado apenas para ambientes de desenvolvimento e testes, pois não faz os processos de um aparelho, como armazenar os XMLs e encaminhar eles para a SEFAZ.

Para instalar os drivers dos aparelhos, deve-se acessar os portais das fabricantes e baixar os executáveis dos drivers, mas sobre o Emulador SEFAZ, nós temos uma documentação que explica passo a passo como realizar esse processo. Basta clicar aqui para entender melhor como realizar esse processo.

Instanciar Componente

Após a instalação do componente, é necessário instanciar a classe no projeto para fazer as modificações necessárias em suas propriedades e também utilizar os seus métodos.

Aqui iremos te mostrar passo a passo como instanciar a classe em três das linguagens, Delphi, C# e VB6.

Delphi

No Delphi há duas formas de instanciar o componente. Você pode arrastar os ícones do componente na barra de ferramentas para dentro do seu unit ou fazê-lo de forma manual, adicionando no uses do projeto:

uses
 spdCFeSat, spdCFeSatDataSets, spdCFeSatType

Em seguida é necessário criar as variáveis das classes, como no exemplo a baixo.

type
  TForm1 = class(TForm)
   CFeSat : TspdCFeSat;
   spdDataSet : TspdCFeSatDataSets;

Independente da forma com que você trouxe as classes ao projeto, agora você deve criar o objeto e direcioná-lo a uma variável:

 CFeSat := TspdCFeSat.Create(nil);
 spdDataSet := TspdCFeSatDataSets.Create(nil);

VB6

Primeiramente, declare o objeto pertencente à classe que faz interação com os servidores da Sefaz

Public spdSAT As spdCFeSatX
Public spdSATDataSet As spdCFeSatDataSetX

Após isso, já na inicialização do Fom, instancie o objeto dentro de uma nova variável.

 Set spdSAT = New spdCFeSatX
 Set spdSATDataSet = New spdCFeSatDataSetX

C#

No início do seu projeto, junto com as bibliotecas importadas, adicione as OCX da Tecnospeed

using CFeSatX;
using CFeSatDataSetX;

Após isso, instancie o objeto dentro de uma nova variável

  public CFeSatX.spdCFeSatX cfeSat = new CFeSatX.spdCFeSatX();
  public CFeSatDataSetX.spdCFeSatDataSetX cfeSatDataset = new CFeSatDataSetX.spdCFeSatDataSetX();

Configurar Propriedades

Antes de utilizar os métodos e funções do componente, é necessário configurar as suas propriedades. Elas podem ser configuradas utilizando um arquivo de configuração (.ini) ou através do código fonte.

Cada propriedade indica uma configuração. Por exemplo, a propriedade "NomeDllSat" determina para qual caminho o Componente irá buscar a DLL de comunicação do SAT. Aqui você acessa as propriedades gerais do componente.

Configurando através do código fonte

É possível preencher as propriedades através do código fonte do sistema. Basta informar os valores desejados para cada uma delas. Você encontra uma lista completa de funções e exemplos de preenchimento das propriedades na seção Propriedades do componente.

Configurando com um arquivo de configuração (ini)

Também é possível preencher as propriedades através de um arquivo de configuração (.ini). Basta informar os valores desejados para cada uma delas e passar o diretório deste arquivo como parâmetro no método LoadConfig. Você encontra uma lista completa de funções e exemplos de preenchimento das propriedades na seção Propriedades do componente.

Fluxo ideal da emissão CFe SAT

O envio e autorização de um Cupom Fiscal SAT funciona de acordo com o fluxo abaixo:

A aplicação vai gerar o arquivo de integração (seja TX2 ou dataset) e vai chamar o método do componente, passando essas informações via parâmetros. O componente, por sua vez, vai gerar um XML através das informações recebidas pela aplicação. Em seguida, acionará a DLL do SAT e encaminhará esse XML para o aparelho.

Uma vez no aparelho, o XML recebe o tratamento necessário, onde mais algumas tags são adicionadas e então, o aparelho faz a validação do XML. Se rejeitado, ele retornará o motivo da rejeição para o componente, que passará isso para a aplicação. A aplicação deve corrigir os pontos citador pelo aparelho e então, gerar um novo arquivo de integração, fazendo um novo envio.

Se autorizado, o aparelho SAT vai retornar a mensagem "Emitido com sucesso + conteúdo notas". E junto com o retorno, vai retornar o XML autorizado desse cupom (chamamos ele de XML AD), codificado em base64. O componente retorna essa mensagem para a aplicação e ele mesmo decodifica o base64 e salva o XML na pasta copiasegurança.

Agora a aplicação só precisa solicitar a impressão do cupom, passando no parâmetro do método, o conteúdo do XML.

Em paralelo a isso tudo, o aparelho SAT vai armazenar esse XML em sua memória, para que ele mesmo faça o envio do XML já autorizado e validado, para os servidores da SEFAZ.

Gerar arquivo de Integração

Para gerar este arquivo de integração, é necessário preencher alguns campos com os valores corretos. Para informar estes dados, é possível:

• Gerar o arquivo de integração utilizando o Componente DataSets ou o arquivo TX2;
• Manter o arquivo XML (caso o sistema já gere).

Utilizando Datasets ou arquivo TX2

Para gerar o arquivo de integração utilizando Componente DataSets ou um arquivo TX2, é necessário seguir o exemplo presente nas nossas demonstrações. Consulte também o nosso dicionário de dados, lá vai encontrar todas as tags disponíveis na NFC-e.

Mantendo o arquivo XML

Caso o arquivo XML já seja gerado pelo sistema, não é necessário alterar para o TX2 ou o Componente DataSets. Basta manter o arquivo XML que já é gerado.

Validando XML

O CF-e SAT, assim como a NFC-e, pode apresentar falhas de esquema, mas infelizmente, o retorno vindo do aparelho não é tão explicativo, vindo apenas como "Erro desconhecido" ou "Erro não identificado". Nesses casos, você deve realizar uma validação no XML de envio, em busca da falha para poder autorizar o cupom.

Localizando XML de envio

O componente sempre salva os arquivos de comunicação que ele faz com o SAT, ou seja, os XMLs de envio e de retorno que ele envia e recebe, respectivamente.

Para localizar esses XMLs, primeiro precisamos olhar para a propriedade DiretorioLog. O componente vai olhar o caminho configurado nessa propriedade, para então salvar os arquivos de envio e retorno. Caso não se lembre dessa propriedade, vamos voltar ao momento da configuração de propriedades e ver onde ela está.

Ao localizar a pasta do logs, agora você precisa localizar o arquivo referente ao envio que fez. Ele vai ter o sufixo -env-cfe.xml.

Validando XML

Agora que localizamos o arquivo, basta seguir esses passos para validar o arquivo. Com isso, vai ter as informações necessárias para autorizar o cupom. Se tiver dúvidas sobre os valores das tags, consulte o nosso dicionário de dados.

Retornos

Caso ocorra uma rejeição, é necessário corrigi-la antes de enviar novamente o Cupom. É possível encontrar uma explicação de como resolver a maioria das rejeições e significado dos retornos em nossa documentação sobre Retornos.

Enviar Cupom

O envio do CF-eSAT funciona de forma síncrona para o aparelho, isso significa que o retorno do seu envio, será a informação dizendo se o cupom foi autorizado ou não, sem a necessidade de uma consulta.

O ambiente do envio do cupom é controlado pelo aparelho SAT (sendo ele de desenvolvimento ou não).

Para enviar o cupom, é necessário utilizar o método EnviarDadosVenda.

Exemplo de nota autorizada:

418062|06000|0000|Emitido com sucesso + conteudo notas.|||PEMJZT48aW5mQ0ZlIElkPSJDRmUzNTE5MDIxMjY2MDYwMDAwMDE2NTU5MDAwNjcw
MDU2MDAwMDE1ODU3MTQ0OCIgdmVyc2FvPSIwLjA3IiB2ZXJzYW9EYWRvc0VudD0i
MC4wNyIgdmVyc2FvU0I9IjAxMDAwMCI+PGlkZT48Y1VGPjM1PC9jVUY+PGNORj44
NTcxNDQ8L2NORj48bW9kPjU5PC9tb2 (continua)

Exemplo de nota rejeitada:

954223|06010|1999|Erro desconhecido||

Imprimir Cupom

O CF-eSAT pode ser impresso na impressora ou salvo como um arquivo PDF. Em ambos os casos, é necessário informar o conteúdo de um XML de um cupom autorizado pelo aparelho SAT.

Impressora

Para imprimir o cupom, é necessário utilizar o método ImprimirCFeSAT. Como parâmetro, é necessário informar o XML autorizado, o caminho para o arquivo de modelo do DANFCE (extensão .rtm), e o nome da impressora que será utilizada para imprimir (caso seja vazio, será utilizada a impressora padrão do Windows).

PDF

Para exportar o CFeSAT em PDF, é necessário utilizar o método ExportarCFeSAT. Como parâmetro, é necessário informar o XML autorizado, o caminho para o arquivo de modelo do DANFCE (extensão .rtm), e o diretório que o PDF deve ser salvo (caso seja vazio, será mostrada a tela de salvar arquivo do Windows).

Cancelar Cupom

O CF-eSAT pode ser cancelada em até 30 minutos após a autorização. Para cancelar um cupom, ele deve estar autorizado.

Para cancelar o cupom, é necessário utilizar o método CancelarUltimaVenda. Como parâmetro, é necessário informar a chave desta NFC-e, o número de protocolo de registro, uma justificativa de cancelamento, a data e hora de cancelamento, a sequência deste evento, e o fuso horário.

Imprimir Cupom Cancelado

Para imprimir uma nota que foi cancelada, é necessário utilizar o método ImprimirCFeSATCancelada. Como parâmetro o XML destinatário de autorização (XML AD), o XML de cancelamento (XML ADC), o caminho do arquivo de impressão (arquivo .rtm) e o nome da impressão (se não informado, a impressão sairá na impressora padrão da máquina).