...
Para entender melhor o fluxo de integração mostramos abaixo,através de um passo a passo a ordem de execução das funções em uma rotina de venda, bem como a execução de uma função que irá consultar informações diretamente do Fiscal Manager.
...
Considerando uma venda (NFC-e ou SAT), que possua 2 produtos e uma única forma de pagamento, as seguintes funções serão utilizadas:
...
Lembrando que cada uma das funções recebe um retorno de execução através de uma string com conteúdo em formato JSON, o tratamento destes retornos é de extrema importância para eventuais situações adversas durante a operação da aplicação. |
...
...
Nos casos onde serão capturadas informações do sistema, o fluxo operacional também é parecido, veja:
...
A string de retorno não possui quebra de linhas, a apresentação acima "identada" tem como objetivo facilitar a visualização do conteúdo retornado. |
...
...
A nova versão do Fiscal Manager contempla recursos para utilização de uma API RestFul.
...
Emitir Cupons.
Registrar Pagamentos.
Enviar emails.
Obter informações diversas, como número de notas e etc.
...
...
...
Antes de prosseguirmos com mais detalhes sobre este novo método de integração, é importante apresentarmos um breve resumo do que é uma API RestFul.
...
Serviços RestFul são largamente utilizados em web services através de uso APIS que por sua vez, permitem acesso aos serviços disponibilizados.
...
...
Um dos principais itens na arquitetura RestFul são as URLs do sistema e os seus resources. Um recurso (resource), usa os métodos do protocolo HTTP para se comunicar: No gráfico abaixo, ilustramos esta interação.
Arquitetura RestFul.
...
As ações executadas para estes serviços, utilizam a tecnologia JSON para troca de informações entre a Plataforma Fiscal (APIOne) e sua aplicação comercial.
...
...
...
Agora que já conhecemos um pouco sobre a arquitetura RestFul, podemos voltar ao processo de integração do Fiscal Manager. Como já visto anteriormente, a integração através da API de serviços RestFul, está disponível nas versões:
02.00.00: Fiscal Manager NFC-e
3.0.0: Fiscal Manager SAT
Cada recurso da API possui uma URL que dá acesso aos detalhes do mesmo, esta documentação está vinculada ao Fiscal Manager para acessá-la utilize a URL: http://localhost:9999/docs/#/
É imprescindível que o Fiscal Manager esteja instalado e em execução para que você tenha acesso a lista de serviços da API. |
...
Nos próximos tópicos abordaremos em detalhes cada um dos serviços RestFul disponíveis na API de integração com o Fiscal Manager.
...
...
Neste tópico, apresentamos todos os recursos disponíveis para a integração com o Fiscal Manager NFC-E e SAT.
...
Método: | POST |
Descrição: | Utilize este recurso da API para iniciar/abrir um novo |
Modelo JSON (Envio e Retorno): |
...
Método: | POST |
Descrição: | Utilize este recurso para o registro de itens na venda, lembrando que o registro de um item envolve informações relacionadas ao produto e também ao imposto vinculado a ele. |
Modelo JSON (Envio e Retorno): |
...
Método: | DELETE |
Descrição: | Utilize este recurso da API quando houver a necessidade de estorno de um item registrado na venda. |
Modelo JSON (Envio e Retorno): |
...
Método: | POST |
Descrição: | Utilize este recurso para registrar as formas de pagamento a serem utilizadas para a totalização da nota. Obs. É possível dentro da nota o registro de mais de um meio de pagamento. |
Modelo JSON (Envio e Retorno): |
...
Método: | DELETE |
Descrição: | Utilize este recurso quando houver necessidade de estorno de um meio de pagamento registrado na venda. |
Modelo JSON (Envio e Retorno): |
...
Método: | POST |
Descrição: | Utilize este recurso para fechar (concluir) a operação de venda. |
Modelo JSON (Envio e Retorno): |
...
Método: | POST |
Descrição: | Utilize este recurso caso seja necessário o estorno/cancelamento de uma venda. |
Modelo JSON (Envio e Retorno): |
...
Método: | POST |
Descrição: | Utilize este recurso quando houver necessidade de inutilização de uma determinada faixa de notas perante a Sefaz. Obs. Tal operação só é permitida para documentos NFC-e e NF-e, não sendo válida para documentos CF-e (SAT). |
Modelo JSON (Envio e Retorno):_ |
...
Método: | GET |
Descrição: | Utilize este recurso para listar documentos emitidos através dos filtros de pesquisa disponibilizados. Obs. Essa função permite a listagem dos documentos de forma paginada. |
Modelo JSON (Envio e Retorno): |
Método: | GET |
Descrição: | Utilize este recurso para efetuar a consulta de um documento através do seu ID de identificação. |
Modelo JSON (Envio e Retorno): | http://localhost:9999/docs/#!/documento/getFromIdentificador |
Método: | POST |
Descrição: | Utilize este recurso para cancelar um documento. |
Modelo JSON (Envio e Retorno): |
Método: | POST |
Descrição: | Utilize este recurso para transmissão da nota via email. Obs. para localização da nota podem ser utilizados: seu identificador ou série e número da mesma. |
Modelo JSON (Envio e Retorno): | http://localhost:9999/docs/#!/documento/enviarDocumentoPorEmail |
Método: | GET |
Descrição: | Utilize este recurso para consultar uma determinada nota através de seu número e série. |
Modelo JSON (Envio e Retorno): | http://localhost:9999/docs/#!/documento/getFromIdentificador_0 |
Método: | POST |
Descrição: | Utilize este recurso para transmissão da nota por email pesquisando a mesma através de seu número e série. |
Modelo JSON (Envio e Retorno): | http://localhost:9999/docs/#!/documento/enviarDocumentoPorEmail_0 |
Método: | GET |
Descrição: | Utilize este recurso para consulta de status de uma impressora Bematech que esteja instalada e configurada no Fiscal Manager. A consulta retornará informações sobre os sensores de papel, tampa e estado da impressora. |
Observação: | Para uma impressora spooler o retorno será "online" para não quebrar a compatibilidade, pois o Fiscal Manager não tem acesso às informações do spooler. |
Modelo JSON (Envio e Retorno): |
Método: | POST |
Descrição: | Utilize este recurso para a impressão de um documento na impressora configurada no Fiscal Manager. Obs. Esta operação recebe um conteúdo binário para a impressão, e caso receba um cabeçalho Content-Transfer-Enconding com o valor base64, o conteúdo recebido será também codificado em base64. |
Modelo JSON (Envio e Retorno): |
Método: | POST |
Descrição: | Utilize este recurso para realizar a impressão de uma DANFE através de sua chave de acesso. |
Modelo JSON (Envio e Retorno): |
Método: | POST |
Descrição: | Utilize este recurso para realizar a impressão de uma DANFE através de sua chave de acesso. |
Modelo JSON (Envio e Retorno): | http://localhost:9999/docs/#!/impressora/imprimirPorNumeracao |
Método: | POST |
Descrição: | Utilize este recurso para realizar o acionamento da gaveta conectada a impressora. É imprescindível que a impressora esteja corretamente instalada e também configurada no Fiscal Manager. |
Observação: | Com impressora spooler a gaveta deve ser configurada diretamente no driver, em Propriedades da Impressora>Configurações do Dispositivo>Opções instaláveis. |
Modelo JSON (Envio e Retorno): |
Nome | Informações sobre o sistema |
Método: | GET |
Descrição: | Utilize este recurso para consultar informações do Fiscal Manager, como: Quantidade de notas rejeitadas e dados do certificado digital. |
Modelo JSON (Envio e Retorno): | http://localhost:9999/docs/#!/sistema/getInformacoesDoSistema |
Método: | GET |
Descrição: | Utilize este recurso para consultar e visualizar as configurações do Fiscal Manager. |
Modelo JSON (Envio e Retorno): |
Método: | POST |
Descrição: | Utilize este recurso para aplicar ajustar configurações específicas do Fiscal Manager. |
Modelo JSON (Envio e Retorno): |
Método: | GET |
Descrição: | Utilize este recurso para pesquisar uma configuração específica do Fiscal Manager, baseada em seu nome. |
Modelo JSON (Envio e Retorno): |
Método: | GET |
Descrição: | Utilize este recurso para obter informações do modo de contingência. Obs. O retorno da função sempre indicará o estado atual do sistema em relação a situação de operação ON-LINE ou Contingência. |
Modelo JSON (Envio e Retorno): | http://localhost:9999/docs/#!/sistema/getInformacoesDeContingencia |
Método: | GET |
Descrição: | Utilize este recurso para alterar a forma do modo de tratamento do modo de contingência do Fiscal Manager, onde basicamente: Se a aplicação estiver ON-LINE ao executar o método a resolução das notas mudará para emissão em contingência e vice-versa. |
Modelo JSON (Envio e Retorno): | http://localhost:9999/docs/#!/sistema/alterarModoDeContingencia |
...
Os exemplos foram categorizados através do tipo de método utilizado. |
...
Recurso utilizado: | Informações sobre o sistema |
Tipo de dados de Envio: | application/JSON |
Tipo de dados de Retorno: | application/JSON |
Detalhes da operação: | Este método deve consultar informações do Fiscal Manager retornando um JSON com as seguintes informações: Versão do Fiscal Manager. Número total de notas rejeitadas. Número total de Notas rejeitas emitidas em contingência. Situação do Certificado digital. Data de expiração do certificado. Dias restantes para expirar. |
_Observação _: | Em caso de sucesso a resposta será: (Status 200) SuccessFull Operation. |
...
1{
2 "versao": "02.00.00 build 01",
3 "totalNotasRejeitadas": 1,
4 "totalNotasRejeitasEmitidasContingencia": 0,
5 "certificado": {
6 "situacao": "No prazo",
7 "dataExpiracao": "03/04/2017",
8 "diasParaExpiracao": 97
9 }
10}
...
...
Recurso utilizado: | Abrir um cupom para venda. |
Tipo de dados de Envio: | application/JSON |
Tipo de dados de Retorno: | application/JSON |
Detalhes da operação: | Este método abrirá o registro de uma venda. |
_Observação _: | Em caso de sucesso a resposta será: (Status 200) SuccessFull Operation. |
...
1{
2 "versao": "3.10",
3 "configuracao": {
4 "imprimir": true,
5 "email": true
6 },
7 "identificacao": {
8 "cuf": "41",
9 "cnf": "00005000",
10 "natOp": "VENDA",
11 "indPag": 0,
12 "mod": "65",
13 "serie": "768",
14 "nnf": "5000",
15 "dhEmi": "2016-12-29T14:06:57-02:00",
16 "tpNF": "1",
17 "idDest": 1,
18 "tpImp": 4,
19 "tpEmis": 1,
20 "cdv": 8,
21 "tpAmb": 2,
22 "finNFe": 1,
23 "indFinal": 1,
24 "indPres": 1,
25 "procEmi": 0,
26 "verProc": "1.0.0.0",
27 "cMunFG": "4106902"
28 },
29 "emitente": {
30 "cnpj": "82373077000171",
31 "endereco": {
32 "nro": "0",
33 "uf": "PR",
34 "cep": "81320400",
35 "fone": "4184848484",
36 "xBairro": "CABRAL",
37 "xLgr": "AV Teste",
38 "cMun": "4106902",
39 "cPais": "1058",
40 "xPais": "BRASIL",
41 "xMun": "Curitiba"
42 },
43 "ie": "1018146530",
44 "crt": 3,
45 "xNome": "BEMATECH SA",
46 "xFant": "BEMATECH"
47 },
48 "destinatario": {
49 "cpf": "76643539129",
50 "endereco": {
51 "nro": "842",
52 "uf": "PR",
53 "cep": "80020320",
54 "fone": "41927598874",
55 "xBairro": "Centro",
56 "xLgr": "Marechal Deodoro",
57 "cMun": "4106902",
58 "cPais": "1058",
59 "xPais": "Brasil",
60 "xMun": "Curitiba"
61 },
62 "indIEDest": 9,
63 "email": "[email protected]",
64 "xNome": "NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL "
65 }
66}
...
...
Recurso utilizado: | Estornar o registro de uma venda (cupom/nota). |
Tipo de dados de Envio: | URL Request |
Tipo de dados de Retorno: | application/JSON |
Detalhes da operação: | Este irá estornar uma nota gerada. |
Parâmetros de envio: | Número da sessão do cupom URL REQUEST: http://localhost:9999/api/v1/documento/cupom/ Exemplo: http://localhost:9999/api/v1/documento/cupom/67d60984590b40e5a7218e77d1fbdfd6 |
_Observação _: | Em caso de sucesso a resposta será: (Status 200) SuccessFull Operation. |
...
1{
2 "sucesso": true,
3 "codigo": 9500,
4 "descricao": "Operação realizada com sucesso"
5}
...
...
Os exemplos foram categorizados através do tipo de método utilizado. |
...
...
Recurso utilizado: Informações sobre o sistema |
Tipo de dados de Envio:application/JSON |
Tipo de dados de Retorno: application/JSON |
Detalhes da operação: Este método deve consultar informações do Fiscal Manager retornando um JSON com as seguintes informações: Versão do Fiscal Manager. Número total de notas rejeitadas. Número total de Notas rejeitas emitidas em contingência. Situação do Certificado digital. Data de expiração do certificado. Dias restantes para expirar. |
_Observação _: |
Em caso de sucesso a resposta será: (Status 200) SuccessFull Operation. |
...
1{
2 "versao": "02.00.00 build 01",
3 "totalNotasRejeitadas": 1,
4 "totalNotasRejeitasEmitidasContingencia": 0,
5 "certificado": {
6 "situacao": "No prazo",
7 "dataExpiracao": "03/04/2017",
8 "diasParaExpiracao": 97
9 }
10}
...
...
Recurso utilizado: Atualizar configurações do Fiscal Manager SAT. |
Tipo de dados de Envio:application/vnd+Bematech.fmsatconf-v1+json |
Tipo de dados de Retorno: application/vnd+Bematech.resposta-v1+json |
Detalhes da operação: Este irá cancelar uma nota gerada. |
_Observação _: |
Em caso de sucesso a resposta será: (Status 200) SuccessFull Operation. Este método não possui Parâmetros de retorno. |
...
1{
2 "configuracao": [{
3 "nome": "PROXY",
4 "valor": "0"
5 }, {
6 "nome": "PRINT_LOGO",
7 "valor": "1"
8 }]
9}
...
...
Recurso utilizado: Abrir um cupom para venda. |
Tipo de dados de Envio:application/JSON |
Tipo de dados de Retorno: application/JSON |
Detalhes da operação: Este método abrirá o registro de uma venda. |
_Observação _: |
Em caso de sucesso a resposta será: (Status 200) SuccessFull Operation. |
...
1{
2 "identificacao": {
3 "cnpj": "16716114000172",
4 "numeroCaixa": "001",
5 "signAC": "SGR-SAT SISTEMA DE GESTAO E RETAGUARDA DO SAT"
6 },
7 "emitente": {
8 "cnpj": "61099008000141",
9 "ie": "111111111111",
10 "indRatISSQN": "S"
11 },
12 "destinatario": {
13 "cpf": "09324114107",
14 "xNome": "Paulo"
15 },
16 "entrega": {
17 "cpf": "09324114107",
18 "endereco": {
19 "xLgr": "Rua Teste",
20 "nro": "450",
21 "xCpl": "teste",
22 "xBairro": "Fazendinha",
23 "xMun": "Curitiba",
24 "uf": "PR"
25 }
26 }
27}
...
...
Recurso utilizado: Estornar o registro de uma venda (cupom/nota). |
Tipo de dados de Envio:application/JSON |
Tipo de dados de Retorno: application/JSON |
Detalhes da operação: Este irá estornar uma nota gerada. |
_Observação _: |
Em caso de sucesso a resposta será: (Status 200) SuccessFull Operation. |
Exemplo de JSON de Retorno
JSON de retorno (NFC-E).
1{
2 "sucesso": true
3}
...
...
Para entender melhor o fluxo de integração quando somente a APIOne é utilizada no processo, apresentamos também alguns fluxos operacionais que ilustram as rotinas de integração.
...
Considerando uma venda (NFC-e ou SAT), que possua 2 produtos e uma única forma de pagamento, os seguintes recursos da API serão utilizados:
...
Lembrando que cada uma dos recursos/serviços da API recebe um retorno de execução também no formato JSON o tratamento destes retornos é de extrema importância para eventuais situações adversas durante a operação da aplicação. |
...
Considere a execução da leitura de informações do sistema. para tal utilize o seguinte recurso da APIOne:
...
{
"versao": "Fiscal Manager SAT - 3.0.0",
"totalNotasRejeitadas": 0,
"totalNotasRejeitasEmitidasContingencia": 0
}
...
...
A Plataforma Fiscal da Bematech, é composta por uma série de componentes que juntos permitem a integração de softwares de automação comercial para a emissão documentos NFC-e e CF-e.
...
...
Fiscal Manager NFC-e: É o núcleo da Plataforma Fiscal Bematech, sendo o responsável por gerar e assinar digitalmente os arquivos XML para emissão da NFC-e. Ele também gerencia a entrada e saída de contingência bem como também realizar a impressão da DANFE ao final do processo.
...
Existe também a versão SAT do Fiscal Manager, suas funcionalidades são similares a versão NFC-e no entanto, o Fiscal Manager não transmite as notas para Sefaz mas sim para o hardware SAT que se encarregará do processo. |
Além do Fiscal Manager a Plataforma Fiscal possui também um conjunto de componentes que oferece várias formas de integração com sua aplicação, dentre eles podemos citar:
Virtual ECF + Biblioteca Bemafi32.dll: Componentes para integração através de modo compatibilidade (aplicações já integradas com ECF). Obs. Válido tanto para NFC-e quanto para SAT.
BemaNFCe.dll: Biblioteca para integração direta com o Fiscal Manager possui funções específicas para comunicação com serviços NFC-e da Bematech de forma mais simplificada pois não trabalha com modo compatibilidade. Obs. Exclusivo para NFC-e.
APIOne: Todas as funcionalidades do Fiscal Manager, disponíveis em uma API que elimina o uso de dlls e também do Virtual ECF para a integração.
...
...
...
Legalmente todos os documentos transmitidos eletronicamente ao Fisco devem ser assinados digitalmente, para tal, adotamos como padrão a utilização do certificado digital do tipo "e-CNPJ A1", abaixo listamos alguns benefícios deste tipo de certificado:
...
O formato do arquivo para importação deve obedecer o padrão PFX. |
...
...
O CSC é um código de segurança alfanumérico disponibilizado pelo Fisco e de conhecimento apenas do Contribuinte. Sua função é, em conjunto com o Certificado Digital, garantir a autoria dos arquivos gerados e enviados aos servidores da Secretaria da Fazenda (SEFAZ).
...
Caso a Software House ou o contribuinte não possuam uma IE (Inscrição Estadual) válida na UF, a homologação não precisa ser interrompida e para fins de desenvolvimento pode-se utilizar o código CSC genérico da SEFAZ Amazonas! Para mais informações acesse: http://portalnfce.sefaz.am.gov.br/desenvolvedor/ambiente-de-homologacao-para-desenvolvedores/ |
...
...
Você pode fazer o download do Fiscal Manager atualizado através do link: http://bematechpartners.com.br/wp01/?page_id=58
Disponibilizamos também, alguns exemplos de utilização do Fiscal Manager no link: http://bematechpartners.com.br/wp01/?page_id=56
...
...
Pensando na praticidade das operações de rollout em seus clientes, a Plataforma Fiscal Bematech adotou o modelo de licenciamento online para os produtos de NFC-e e S@T, através do portal License Admin (LA). O LA consiste em um ambiente online onde o próprio desenvolvedor possui autonomia para inserir, ampliar ou reduzir a quantidade de licenças disponíveis da Plataforma Fiscal aos seus clientes.
Acessando o Portal LA pelo link: http://lalicencaplataformafiscal.bematechtotvs.com.br/, para se cadastrar acesse o link "Novo Cadastro". Após preencher os dados do formulário, e confirmar seu cadastro, será enviado um link de para o email registrado. Concluído o cadastro e a confirmação do mesmo ao acessar o License Admin será exibido o DashBoard inicial da aplicação que apresenta as informações relevantes as licenças dos clientes vinculados a sua Software House. Todo o passo a passo para o cadastro e gestão de licenças, está disponível no link "Help" disponível no menu superior do portal (imagem abaixo) portal e sempre que necessário, você pode contar com nosso time suporte técnico para sanar eventuais dúvidas e questionamentos.
Figure 3. Portal License Admin.
...
...
...
...
...
Ao iniciar a instalação a seguinte tela será apresentada:
...
Figure 15. Conclusão do processo de instalação.
...
...
...
Ao iniciar a instalação a seguinte tela será apresentada:
...
Para usar o método de integração através da API selecione a opção "Fiscal Manager SAT- SINGLE" |
...
O próximo passo da instalação é definir o caminho onde o Fiscal Manager será instalado.
Figure 18. Path da instalação.
Definido o path de instalação, clique em "Instalar" para que o processo seja iniciado antes será exibida uma tela apresentando um resumo da instalação.
Figure 19. Resumo dos itens a serem instalados.
Ao término do processo o instalador irá exibir a tela de conclusão, e não sequência iniciar o Painel de Controle do Fiscal Manager.
Figure 20. Término da instalação.
O painel de controle do Fiscal Manager SAT é carregado através do browser padrão configurado em seu sistema operacional, para abrir a aplicação utilize:
...