Guia Geral - CT-e OS – Central de Atendimento

O Componente CT-e OS da Tecnospeed é uma biblioteca contendo todos os métodos necessários para emitir um Conhecimento de Transporte eletrônico. É a escolha ideal para quem pode consumir OCX e prefere manter todo o processo de mensageiria do CT-e OS 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:

Instalar Componente
Instanciar Componente CTe OS
Configurando as propriedades
Entendendo o fluxo de emissão
Gerar o arquivo de integração
Assinar um XML
Rejeições
Enviar CTe OS
Imprimir CTe OS
Cancelar CTe OS

Instalar Componente CTe OS

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 CT-e OS 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.

Além do Componente CT-e OS, você também precisará de um CNPJ com Inscrição Estadual e um certificado digital deste CNPJ cadastrado no Web Service da SEFAZ.

Existem dois instaladores disponíveis para download na Central do Cliente: O Setup CTe OS Full(deve ser instalado no ambiente de desenvolvimento) e o Setup CTe OS Dependencies(deve ser instalado 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/CTeOS/Arquivos). É necessário colocá-los no ambiente do cliente e configurar o diretório delas nas propriedades DiretorioEsquemas, DiretorioTemplates, ArquivoServidoresHom e ArquivoServidoresProd.

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:

CTeOSX.dll
CTeOSDataSetX.dll
spdCCeCTeOSDataSetX.ocx
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 CT-e OS 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 CTeOS 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 CTeOS, conforme a imagem abaixo:

Instanciar o 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
spdCTeOS, spdCTeOSUtils, spdCTeOSDataSet, spdCTeOSDacte

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

type
  TForm1 = class(TForm)
   CTeOS: TspdCteOS;
   CTeOSDataSet: TspdCteOSDataSet;
   fUtils: TspdGovUtils;

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

CTeOS := TspdCTeOS.Create(nil);
CTeOSDataSet := TspdCTeOSDataSet.Create(nil);
fUtils := TspdGovUtils.Create(nil);

VB6

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

Dim CTeOS As CTeOSX.spdCTeOSX
Dim CTeOSDataSet As CTeOSDataSetX.spdCTeOSDataSetX

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

Set CTeOS = New CTeOSX.spdCTeOSX
Set CTeOSDataSet = New CTeOSDataSetX.spdCTeOSDataSetX

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

using CTeOSx
using CTeOSDataSetX;

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

CTeOS = new CTeOSX.spdCTeX();
CteOSDataSetX = new CTeOSDataSetX.spdCTeDataSetX();

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 "Ambiente" determina para qual servidor o Componente irá enviar o conhecimento (o de homologação ou de produção). Estas configurações estão divididas em três tipos: as propriedades gerais do componente, as propriedades de Diretório e as propriedades de impressão (DACTE).

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.

//[CTEOS]
spdCTeOS.UF := 'PR';
spdCTeOS.CNPJ := '08187168000160';
spdCTeOS.NomeCertificado := 'CN=TECNOSPEED SA:08187168000160, OU=Certificado PJ A1, O=ICP-Brasil, C=BR, S=, L=, E=, SE=6D 8C 19 04 25 53 86 82';
spdCTeOS.ArquivoServidoresHom := 'C:\Program Files\TecnoSpeed\CTeOS\Arquivos\cteosServidoresHom.ini';
spdCTeOS.ArquivoServidoresProd := 'C:\Program Files\TecnoSpeed\CTeOS\Arquivos\cteosServidoresProd.ini';
spdCTeOS.TipoCertificado := File;
spdCTeOS.DiretorioEsquemas := 'C:\Program Files\TecnoSpeed\CTeOS\Arquivos\Esquemas\';
spdCTeOS.DiretorioTemplates := 'C:\Program Files\TecnoSpeed\CTeOS\Arquivos\Templates\';
spdCTeOS.DiretorioLog := 'Log\';
spdCTeOS.DiretorioLogErro := 'LogErro\';
spdCTeOS.DiretorioTemporario := '';
spdCTeOS.Ambiente := 1;
spdCTeOS.Repositorio := CURRENT_USER_STORE;
spdCTeOS.ValidarEsquema := 1;
spdCTeOS.PINCODE := '';
spdCTeOS.VersaoManual := 3.00a;
spdCTeOS.MaxSizeLoteEnvio := '500';
spdCTeOS.DiretorioXmlTomadorServico := 'XmlTomadorServico\';
spdCTeOS.AnexarDactePDF := 1;
spdCTeOS.IgnoreInvalidCertificates := 1;
spdCTeOS.TimeOut := '0';
spdCTeOS.Usuario := '';
spdCTeOS.Senha := '';
spdCTeOS.ConexaoSegura := '1';
spdCTeOS.Proxy := '';
spdCTeOS.ModoOperacao := 'NORMAL';
spdCTeOS.CaminhoCertificado := '';
spdCTeOS.SenhaCertificado := '';

//[DACTE]
spdCTeOS.ModeloRetrato := 'C:\Program Files\TecnoSpeed\CTeOS\Arquivos\Templates\3.00a\DACTE\Retrato.rtm';
spdCTeOS.ModeloPaisagem := 'C:\Program Files\TecnoSpeed\CTeOS\Arquivos\Templates\3.00a\DACTE\Paisagem.rtm';
spdCTeOS.ModeloRTMCCe := 'C:\Program Files\TecnoSpeed\CTeOS\Arquivos\Templates\cce\Impressao\modeloCCe.rtm';
spdCTeOS.LogotipoEmitente := 'C:\Program Files\TecnoSpeed\CTeOS\Arquivos\Templates\3.00\DACTE\TECNOSPEED.jpg';
spdCTeOS.FraseHomologacao := 'SEM VALOR FISCAL';
spdCTeOS.QtdeCopias := '1';

//[MAIL]
spdCTeOS.Servidor := 'smtp.gmail.com';
spdCTeOS.EmailRemetente := 'testedacte@gmail.com';
spdCTeOS.Assunto := 'Exemplo de envio de DACTE por email';
spdCTeOS.Mensagem := 'O arquivo esta em anexo.';
spdCTeOS.Usuario := 'testedacte@gmail.com';
spdCTeOS.Senha := 'tecnospeed';
spdCTeOS.TimeOut := '30000';
spdCTeOS.EmailDestinatario := '';
spdCTeOS.CCo := '';
spdCTeOS.CC := '';
spdCTeOS.Autenticacao := 1;
spdCTeOS.Porta := '0';

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.

[CTEOS]
UF=PR
CNPJ=08187168000160
NomeCertificado=CN=TECNOSPEED SA:08187168000160, OU=Certificado PJ A1, O=ICP-Brasil, C=BR, S=, L=, E=, SE=6D 8C 19 04 25 53 86 82
ArquivoServidoresHom=C:\Program Files\TecnoSpeed\CTeOS\Arquivos\cteosServidoresHom.ini
ArquivoServidoresProd=C:\Program Files\TecnoSpeed\CTeOS\Arquivos\cteosServidoresProd.ini
TipoCertificado=File
DiretorioEsquemas=C:\Program Files\TecnoSpeed\CTeOS\Arquivos\Esquemas\
DiretorioTemplates=C:\Program Files\TecnoSpeed\CTeOS\Arquivos\Templates\
DiretorioLog=Log\
DiretorioLogErro=LogErro\
DiretorioTemporario=
Ambiente=1
Repositorio=CURRENT_USER_STORE
ValidarEsquema=1
PINCODE=
VersaoManual=3.00a
MaxSizeLoteEnvio=500
DiretorioXmlTomadorServico=XmlTomadorServico\
AnexarDactePDF=1
IgnoreInvalidCertificates=1
TimeOut=0
Usuario=
Senha=
ConexaoSegura=1
Proxy=
ModoOperacao=NORMAL
CaminhoCertificado=
SenhaCertificado=

[DACTE]
ModeloRetrato=C:\Program Files\TecnoSpeed\CTeOS\Arquivos\Templates\3.00a\DACTE\Retrato.rtm
ModeloPaisagem=C:\Program Files\TecnoSpeed\CTeOS\Arquivos\Templates\3.00a\DACTE\Paisagem.rtm
ModeloRTMCCe=C:\Program Files\TecnoSpeed\CTeOS\Arquivos\Templates\cce\Impressao\modeloCCe.rtm
LogotipoEmitente=C:\Program Files\TecnoSpeed\CTeOS\Arquivos\Templates\3.00\DACTE\TECNOSPEED.jpg
FraseHomologacao=SEM VALOR FISCAL
QtdeCopias=1

[MAIL]
Servidor=smtp.gmail.com
EmailRemetente=testedacteOS@gmail.com
Assunto="Exemplo de envio de DACTE por email"
Mensagem="O arquivo esta em anexo."
Usuario=testedacteOS@gmail.com
Senha=tecnospeed
TimeOut=30000
EmailDestinatario=
CCo=
CC=
Autenticacao=1
Porta=0

Salvando este arquivo no diretório do exe da aplicação que carrega o componente CTeOS, com o nome cteosConfig.ini, você deve chamar o método:

spdCTeOS.Loadconfig();

Assim as configurações listadas no arquivo serão carregadas para o componente.

Fluxo ideal da emissão CTe OS

No CTe-OS o envio é feito apenas de forma síncrona.

No envio síncrono, a SEFAZ retornará um XML já contendo a situação de autorização ou rejeição, não sendo necessário fazer uma consulta de chave ou recibo após o envio. Este fluxo será abordado em mais detalhes no artigo Enviando um CT-e OS.

Gerando o 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 Dicionário de Dados. Este dicionário possui todos os campos disponíveis, instruções de como iniciar e concluir um arquivo e como informar os grupos que podem se repetir.

Saiba mais sobre o Dicionário de Dados >

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 e, antes de enviar, realizar a assinatura digital deste arquivo.

Assinar XML

Para enviar uma nota à SEFAZ, é necessário realizar uma assinatura digital do XML. Esta assinatura é realizada utilizando um Certificado Digital.

Obtendo o nome do Certificado Digital

Cada certificado possui uma identificação única, que é o que o componente utilizará para selecionar o certificado correto ao realizar a assinatura. É possível listar todos os certificados digitais utilizando o método ListarCertificados.

Este método retornará uma lista com as identificações dos certificado, tanto do modelo A1 quanto do modelo A3 (que possui um cartão físico), instalados no repositório pessoal do Windows. A identificação é uma string parecida com esta:

CN=TECNOSPEED S A:00000000000000, OU=Certificado PJ A1, O=ICP-Brasil, C=BR, S=, L=, E=, SE=00 00 00 00 00 00 00 00

Informando o nome do Certificado Digital

Para selecionar o Certificado Digital que será utilizado na assinatura, basta informar o nome do certificado (esta identificação que o método ListarCertificados retornou) na propriedade NomeCertificado.

Para configurar a propriedade, é possível utilizar um arquivo de configuração (.ini) ou configurar através do código fonte. O artigo Configurando as propriedades detalha o funcionamento das propriedades.

Realizando a assinatura do XML

Para assinar o XML de envio, é necessário utilizar o método AssinarCTeOS. Como parâmetro, é necessário informar o XML sem assinatura como string. O método retornará o mesmo XML passado como parâmetro na função, porém ele terá as tags de assinatura em seu conteúdo.

É importante lembrar que é necessário que o CNPJ do emitente da nota seja o mesmo CNPJ do certificado digital utilizado para realizar a assinatura.

Validar XML

Em alguns casos, antes de enviar o conhecimento à SEFAZ, é importante validar o XML. Esta validação mostrará possíveis rejeições e avisos a serem corrigidos antes de enviar em produção. Para validar um conhecimento, é possível utilizar o validador da Sefaz.

Para utilizar o Validador CT-e OS da SEFAZ, basta colar um XML, no quadro, clicar em Validar e conferir o resultado da validação abaixo.

Acessar o validador da SEFAZ >

Rejeições

Caso ocorra uma rejeição, é necessário corrigi-la antes de enviar novamente a nota. É possível encontrar uma explicação de como resolver a maioria das rejeições na seção Rejeições da nossa documentação. Caso precise de ajuda, fale com a nossa equipe de suporte.

Enviar CTe OS

Antes de enviar, é importante verificar a propriedade Ambiente. Esta propriedade define se o envio será em homologação ou em produção, conforme é explicado no artigo Configurando as propriedades.

Síncrono

Para enviar um conhecimento de forma síncrona, é necessário utilizar o método EnviarCteOS. No envio síncrono, a SEFAZ retornará um XML já contendo a situação de autorização ou rejeição, não sendo necessário fazer uma consulta de chave ou recibo após o envio.

O retorno desta consulta mostrará se o conhecimento foi autorizado (cStat igual a 100) ou qual foi o motivo da rejeição.

Exemplo de CT-e OS autorizado:

<retConsSitCTe versao="3.00" xmlns="http://www.portalfiscal.inf.br/cte">

<tpAmb>2</tpAmb>
<verAplic>PR-v3_0_73</verAplic>
<cStat>100</cStat>
<xMotivo>Autorizado o uso do CT-e</xMotivo>
<cUF>41</cUF>
<protCTe versao="3.00">
<infProt>
<tpAmb>2</tpAmb>
<verAplic>RS20191022085547</verAplic>
<chCTe>41180203964585000158670010000004721060219569</chCTe>
<dhRecbto>2019-12-19T11:02:34-03:00</dhRecbto>
<nProt>941190000031345</nProt>
<digVal>gMSR1/h4T/nA0qaeAKS0Qk2J3tU=</digVal>
<cStat>100</cStat>
<xMotivo>Autorizado o uso do CT-e</xMotivo>
</infProt>
</protCTe>
</retConsSitCTe>

Exemplo de CT-e OS rejeitado:

<retCTeOS versao="3.00" xmlns="http://www.portalfiscal.inf.br/cte">
    <tpAmb>2</tpAmb>
    <verAplic>PR-v3_0_73</verAplic>
    <nRec>431000013208038</nRec>
    <cStat>225</cStat>
    <xMotivo>Rejeição: Falha no Schema XML do CT-e</xMotivo>
    <cUF>41</cUF>
</retCTeOS>

Imprimir CTe

O DACTE 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 conhecimento autorizado na SEFAZ (cStat igual a 100).

Impressora

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

Veja mais sobre o método ImprimirDACTE >

PDF

Para exportar o DACTE em PDF, é necessário utilizar o método ExportarDACTEParaPDF. Como parâmetro, é necessário informar o XML autorizado, o caminho para o arquivo de modelo do DACTE (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 CTe

O atual prazo para o cancelamento de um CT-e OS, é de 7 dias (168 horas), exceto no estado do Mato Grosso, onde o prazo é de apenas duas horas, contados a partir da data que foi emitida sua “Autorização de Uso” (cStat igual a 100).

Para cancelar um CT-e OS, é necessário utilizar o método CancelarCTeOSEvento. Como parâmetro, é necessário informar a chave desta CT-e OS, 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.

Veja mais sobre o método CancelarCTeOSEvento >

Imprimir CTeOS Cancelado

Para imprimir um CT-e OS que foi cancelado, é necessário utilizar o método ImprimirDACTE. Como parâmetro, é necessário informar o XML autorizado, o XML cancelado, o caminho para o arquivo de modelo do DACTE (extensão .rtm), e o nome da impressora que será utilizada para imprimir (caso seja vazio, será utilizada a impressora padrão do Windows).